PingOne provides an out-of-box workflow to authenticate users. In addition, requests from OIDC/OAuth 2 and SAML applications initiate the flow and can redirect the browser to a custom authentication UI. The following diagram shows the authentication flow.
The following walk-through shows the actions required to authenticate a user. This scenario illustrates the following authentication operations:
Initiate an authorization request
Redirect to the authentication UI
Retrieve the flow and present appropriate forms to end users (and submit data) for all required steps.
Redirect to the resume URL when the flow is complete.
The steps that follow illustrate general flow actions. This exploration is not written as a step-by-step process that can be completed successfully.
The following sample shows the GET /{{envID}}/as/authorize
operation for an authorization_code
request. The following sample shows as authorize request for an OIDC/OAuth 2 application.
curl -X GET \
'https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri=https://example.com&scope=p1:read:self:user&acr_values=Multi_Factor'
The response returns a 302
message with a flowID
embedded in the Location
header, which specifies that a call should be made to another resource to continue the authentication flow. The Location
header looks like this:
Location: http://example.com?environmentId=9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7&flowId=acfa3223-aa05-49d5-bab2-b03dc019bb5f
The flowId
returned in Step 1 specifies the flow to run to continue the authentication request. The following sample shows the GET /{{envID}}/flows/{{flowID}}
operation that calls the flow identified by the flowId
.
curl -X GET \
'https://auth.pingone.com/{{envID}}/flows/{{flowID}}'
The response data looks like this. The status
property in the response specifies the next action in the authentication flow. In this flow, the USERNAME_PASSWORD_REQUIRED
action is the next required step:
{
"_links": {
"self": {
"href": "https://auth.pingone.com/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/flows/5318a876-a8de-4d68-be79-b64043ff6490"
},
"usernamePassword.check": {
"href": "https://auth.pingone.com/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/flows/5318a876-a8de-4d68-be79-b64043ff6490"
},
"password.forgot": {
"href": "https://auth.pingone.com/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/flows/5318a876-a8de-4d68-be79-b64043ff6490"
}
},
"id": "5318a876-a8de-4d68-be79-b64043ff6490",
"resumeUrl": "https://auth.pingone.com/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/as/resume?flowId=5318a876-a8de-4d68-be79-b64043ff6490",
"status": "USERNAME_PASSWORD_REQUIRED",
"createdAt": "2019-06-18T18:47:44.750Z",
"expiresAt": "2019-06-18T19:09:07.629Z",
"_embedded": {
"application": {
"name" : "PingOne Admin Console",
"icon" : {
"id" : "<uuid>",
"href" : "[https://assets.pingone.com/ux/ui-library/4.18.0/images/logo-pingidentity.png] "
}
}
}
}
For more information about flow status
values, see Flows.
The required action specified in Step 2 calls the action service to present the appropriate input form to end users, and after input is provided, to submit the data. This operation is performed repeatedly for each action required in the authentication flow, depending on the actions configured in the sign-on policy configuration. It continues until the flow status is COMPLETED
or FAILED
.
For example, the following sample shows the POST /{{envID}}/flows/{{flowID}}
operation that calls the login with username and password action. This operation uses the application/vnd.pingidentity.usernamePassword.check+json
custom media type as the content type in the request header when there is no user associated with the current flow.
curl -X POST "https://auth.pingone.com/{{envID}}/flows/{{flowID}}" \
-H 'Content-type: application/vnd.pingidentity.usernamePassword.check+json' \
-d '{
"username": "jameslymanstone",
"password": "ChangeM3!"
}'
After completing the actions specified by the sign-on policy, the authentication UI redirects the browser to the URL specified in the resumeUrl
property in the flow resource.
The following sample shows the resumeUrl
value constructed by the flow to return the flow back to the authorization service, specifying the flowID
in the request URL.
"resumeUrl": "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/as/resume?flowId=663067c8-3973-4578-adf2-f42514fe3dc1"