Activity - Using PingOne authentication flows


Authentication flows

PingOne provides an out-of-box workflow to authenticate users. Requests to the PingOne authorization service initiates the steps and actions required to verify user credentials, whether the authentication flow is a basic username/password login or a multi-factor authentication process. The flow orchestration service manages the action services needed to verify the user and complete authentication workflow.

Note: When the authentication flow is initiated, the flow orchestration service creates a session and assigns a session token cookie to the session to associate the flow with the session. The examples on this page do not show the Cookie HTTP header or the session token cookie, which should be included in curl requests.

The following diagram shows the PingOne out-of-box authentication flow.

API Model

Note: Responses from some flow orchestration endpoints can include a -- requiredStep HAL link that specifies the URL to an action that requires user interaction. Required steps prompt for input such as entering username/password credentials or a one-time password sent to a registered device in a multi-factor authentication flow.

PingOne authentication flow endpoints

The following activity shows the endpoints required to authenticate a user and return an access token. This scenario illustrates some common operations supported by PingOne Authentication API services, including:

  • Initiate an authorization request
  • Call the flow orchestration service to process the request
  • Validate user credentials
  • Return an access token

Note: The steps below show the endpoints called to complete an authorization_code authorization grant type. For an authorization_code grant, the flow orchestration service returns an authorization code that is then exchanged for an access token.

Step 1: Initiate an authorization request

The following sample shows the GET /{environmentId}/as/authorize operation for an authorization_code request. The request URL specifies a value of code for the response_type parameter to return an authorization code.

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.

Note: The application (client_id) must be configured for the authorization_code flow by specifying authorization_code as the grantType and the response_type set to code.

Step 2: Call the flow orchestration service

The flowId returned in Step 1 specifies the flow to run to continue the login 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}'

The response data returns information that identifies the next step in the authentication flow. In this case, the response includes a stepId that specifies a login action step.

Step 3: Call the step service and validate credentials

The stepId returned in Step 2 calls the step service to continue the login request.

The following sample shows the GET /{environmentId}/flows/{flowId}/steps/{stepId} operation that calls the flow identified by the flowId.

curl -X GET \
  'https://auth.pingone.com/{environmentID}/flows/{flowId}/steps/{stepId}'

The response data returns a URL for an embedded required step to validate the user’s credentials (_embedded.requiredStep._links.validatePassword.href). The validate password action is required if the request is the first time the user’s credentials are submitted.

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" \
-d "{
  "username": "jameslymanstone",
  "password": "ChangeM3!"
}"

For authorization requests that specify acr_values=Multi_Factor, the flow orchestration service initiates another required step to validate the one-time password (OTP) sent to the user’s specified device.

The following sample shows the POST /{environmentId}/flows/{flowId}/steps/{stepId} operation. The user receives the OTP, submits it, and the MFA actions service validates the OTP to complete the credentials verification actions. This operation uses the application/vnd.pingidentity.otp.check+json custom media type as the content type in the request header.

curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}/steps/{stepId}" \
-H "Content-type: application/vnd.pingidentity.otp.check+json" \
-d "{
  "otp": "123456"
}"

Step 4: Call the resume endpoint

After completing the login and MFA actions to validate the user’s credentials, the flow orchestration service redirects to the resume endpoint to continue the authorization flow.

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='

The response data includes a 302 message with code and redirect_uri parameters embedded in the query string of the Location header.

Step 5: Call the token endpoint

For the authorization_code grant type, authorization service calls the token endpoint to pass in the code and exchange it for an access token.

The following sample shows the /{environmentId}/as/token operation.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/as/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d $'{
    "grant_type": "authorization_code",
    "code": "{authCode}",
    "redirect_uri": "{redirect_uri}"
  }'

The response data includes the access token.