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.

PingOne authentication flow endpoints

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.

Step 1: Initiate an authorization request

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

Step 2: Retrieve the flow resource

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.

Step 3: Submit data for the required action

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!"
}'

Step 4: Redirect to the resume endpoint

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"