Activity - Using PingOne authentication flows


Authentication flows

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. A session token (ST) cookie can be set by the Set-Cookie response header when the authentication flow is initiated. The browser will automatically include the cookie in subsequent requests.

The following diagram shows the authentication flow.

API Model

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.

Step 1: Initiate an authorization request

The following sample shows the GET /{environmentId}/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/{environmentID}/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.

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 /{environmentId}/flows/{flowId} operation that calls the flow identified by the flowId.

curl -X GET \
  'https://auth.pingone.com/{environmentID}/flows/{flowId}' \
  -H 'Cookie: ST=<sessionToken>'

The response data returns information that identifies the stepId for the next step in the authentication flow.

Step 3: Submit data for the required step

The stepId returned in Step 2 calls the step service to present appropriate input form to end users, and after input is provided, to submit the data. This operation is performed repeatedly for each of the steps required in the authentication flow, depending on the actions configured in the sign on policy configuration. It continues until the flow status is COMPLETE or FAILED.

For example, the following sample shows the POST /{environmentId}/flows/{flowId}/steps/{stepId} operation that calls the validate password login 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. The operation uses the application/vnd.pingidentity.password.check+json custom media type as the content type in the request header when there is a user associated with the current flow.

curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}/steps/{stepId}" \
-H 'Content-type: application/vnd.pingidentity.usernamePassword.check+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
  "username": "jameslymanstone",
  "password": "ChangeM3!"
}'

Step 4: Redirect to the resume endpoint

After completing the actions specified in the sign-on policy, the authentication UI redirects to the resume endpoint, which is specified in the resumeUrl property in the flow resource.

The following sample shows the /{environmentId}/as/resume operation to return the flow back to the authorization service, specifying the flowID in the request URL.

curl -X GET \
  'https://auth.pingone.com/{environmentId}/as/resume?flowId=' \
  -H 'Cookie: ST=<sessionToken>'