- Receives a Flow ID
- Checks credentials
- Retrieves tokens
-
To initiate the flow, call the standard authorization endpoint.
GET https://localhost:9031/as/authorization.oauth2
Query parameters Parameter Value Description client_id
ac_oic_client
The OAuth client ID configured in PingFederate.
response_type
code
Specifies the Authorization code grant type.
response_mode
pi.flow
Specifies a redirectless flow with JSON responses.
scope
openid
Specifies the OAuth2 scope.
openid
is a reserved scope that enablesid_token
issuance.These are all standard OAuth2 parameters, with the exception of response_mode, which is how PingFederate determines if an authentication flow should be redirected to an authentication portal through a 302 Redirect, or responded to with JSON in a 200 OK.
The following example shows a sample call response.
{ "id": "Bq5XW", "pluginTypeId": "7RmQNDWaOnBoudTufx2sEw", "status": "USERNAME_PASSWORD_REQUIRED", "showRememberMyUsername": false, "showThisIsMyDevice": false, "thisIsMyDeviceSelected": false, "showCaptcha": false, "rememberMyUsernameSelected": false, "_links": { "self": { "href": "https://localhost:9031/pf-ws/authn/flows/Bq5XW" }, "checkUsernamePassword": { "href": "https://localhost:9031/pf-ws/authn/flows/Bq5XW" }, "initiateRegistration": { "href": "https://localhost:9031/pf-ws/authn/flows/Bq5XW" } } }
-
To see what actions the user should take to authenticate, run the
checkUsernamePassword
action with the following command.POST https://localhost:9031/pf-ws/authn/flows/{{flowId}}
Headers Header Value Description X-XSRF-HEADER
test
This custom header ensures that browsers enforce cross-origin resource sharing (CORS) policies when API requests are sent.
Note:The value of this header does not matter.
Content-Type
application/json
Standard API header.
Query parameters Parameter Value Description action
checkUsernamePassword
An action associated with the current authentication state.
The payload will look like the following.
{ "username" : "user.1", "password" : "Password1" }
The call response will look like the following.
{ "id": "Bq5XW", "pluginTypeId": "CmqYYkZJLFOAcDW4Ob1wXw", "status": "COMPLETED", "authorizeResponse": { "code": "qXSrGABNgJpn_JBuiSW8IWIVDkxsIVbsQLLrYH_X" }, "_links": { "self": { "href": "https://localhost:9031/pf-ws/authn/flows/Bq5XW" } } }
Your status is
COMPLETED
, but your code must account for possible error states, such asCREDENTIAL_VALIDATION_FAILED
.You also receive an href that can be used to initiate the next flow so that you don't need to store a table of possible statuses and associated endpoints. Using this over hard-coded endpoints helps future-proof your code against possible future changes to the API.
-
To establish the user's identity and make API calls on their behalf, retrieve
your tokens with the following command.
POST https://localhost:9031/as/token.oauth2
Payload (x-www-form-urlencoded) Payload Value Description client_id
ac_oic_client
The OAuth client ID configured in PingFederate
grant_type
authorization_code
The grant type associated with the specified
client_id
code
{{authCode}}
The code returned in the previous payload
client_secret
abc123DEFghijklmnop4567rstuvwxyzZYXWUT8910SRQPOnmlijhoauthplaygroundapplication
The client secret associated with the specified
client_id
The following is a sample call response.
{ "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIiwicGkuYXRtIjoieDR6diJ9.eyJzY29wZSI6WyJvcGVuaWQiXSwiY2xpZW50X2lkX25hbWUiOiJhY19vaWNfY2xpZW50IiwiYWdpZCI6ImhoMUt3ckQ1RDRWdmVTRmVlVDc2NEEwdFhOaWZHQ2YyIiwiVXNlcm5hbWUiOiI0ZTliNzg0Ny1lZGNiLTM3OTEtYjExYi03NTA1ZjRhNTVhZjQiLCJPcmdOYW1lIjoiUGluZ0lkZW50aXR5IiwiZXhwIjoxNjE5OTQ4NzQyfQ.WoxPBqRJfA4z71KmQYOnOasVmCZMe9HG06QAi2iVCeG9jzUAudjuNs3HOGvYobtr7_VY8pYu8G3DSK3EPvu1Ox2-c_6D89EZeDmQWJATiL2cpkIs2XU1Fb4HpDuFGPSTZUR4ijSdqyWS7XhYZNAF4MQf3LTu3lih7ud5AH0a1VKlK1tE5kP-VXiebjzo0G6A3oAIhQ9Fopnd9NWTJZ734m8OHldfbueFC1aYLf5u1U-8my2PUMHRkmBzFACVRCdRhp1Dlrkj86kJbZ1WVSZ1qItAe0qSrMmTvIWlD5mlIsSDU0Qh9M1m1ZzzKEnQQET_cXJXxs3QRqTFzFWo6DysHA", "refresh_token": "ZTZ2psveZ1qe1ngy82zdM2BUqNAPWqxBcDS3FZlgys", "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEzRVRpSGF0Wjg4czFEMlhLSGstdzRyZkdLYyJ9.eyJzdWIiOiI0ZTliNzg0Ny1lZGNiLTM3OTEtYjExYi03NTA1ZjRhNTVhZjQiLCJhdWQiOiJhY19vaWNfY2xpZW50IiwianRpIjoiT2pGaWhQNjNmalJ3OHBiNTBrT1lqNCIsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0OjkwMzEiLCJpYXQiOjE2MTk5NDE1NDAsImV4cCI6MTYxOTk0MTg0MCwiYXV0aF90aW1lIjoxNjE5OTQxNTQwfQ.bJzboJy2oWbdhBbSPBqeKmHwQLqE4hL1M0aIleMdoD9GbQ0PEENjb4PE-rGoxrBhBqUxeoHvqBF-98BQBbUsYVJwwMOAwZ4MU9FnOEf2kpZ-9slAot2dWGHef9S6P-So1doi6bbqp9aPcYJpzyvOKCJRHMzZtiPclRHrIUaU7xRcoFbpfZ-8mr6icJUikqzrtaYqGVxTlILPgenI8c0Aau103yfrezRKbK3LJSdKZ7CJ5NJBhQXOqd7jsyMfEa8AQOT8pWYw7He53Y0FF1jCK6leQIT_ZtXxsl8Gi1-KvXyt2FNm02CPIDMrbpp2cI_054xDc6X7_BchvKlI9mjGiw", "token_type": "Bearer", "expires_in": 7199 }
You receive three tokens in the response, marking the end of the authentication process.