Understanding PingOne authentication flow states


Authentication workflow states

An application’s sign-on policy assignments determine the flow states and the corresponding actions required to complete an authentication workflow. When the authentication workflow begins, the flow gets the list of sign-on policies assigned to the application and evaluates the policy action conditions that must be met to complete sign on. The sign-on policy evaluation logic is shown in the diagram below:

Policy logic

For more information about sign-on policies, see Sign-on policies, Sign-on policy actions, and Sign-on policy assignments.

Common authentication actions

The PingOne flow API supports single-factor and multi-factor actions to complete an authentication workflow. For a single-factor login flow, there are four branches that allow the user to submit a username and password (or create a new account). PingOne also supports an identity first discovery action that identifies the user and determines the user’s applicable identity provider and authentication methods. For a multi-factor authentication action, there are two branches in which either a one-time password (OTP) or a push confirmation is used as the second factor in the authentication workflow.

PingOne supports a progressive profiling action that prompts users to provide additional data at sign on. This action type does not authenticate users. It is used only to obtain additional profile data.

The following sections provide flow diagrams and descriptions of the sign-on actions required to complete the authentication flow. For more information about flow states and their associated sign-on actions, see Flows.

Login action

Authentication flows start with a call to the /{environmentId}/as/authorize endpoint. The response to an authorize request returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for the authentication workflow. For a new session, the user’s browser is redirected to the sign-on screen that prompts for a PingOne username and password (or, based on the sign-on policy configuration, provides access to an external identity provider’s sign-on URL).

For an existing session, the user’s browser is redirected to a sign-on screen that prompts for a password only. The following diagram shows the flow options for the USERNAME_PASSWORD_REQUIRED and PASSWORD_REQUIRED flow states:

Flow overview

The login flow consists of the following four branches, which can be chosen to submit the username and password, recover a forgotten password, or create account credentials to complete the sign-on flow:

  • Sign on with username/password

    This flow verifies the username and password submitted by the user through the sign-on screen. For more information, see Sign on with username/password.

  • Forgot password

    If enabled, the recover password flow initiates actions to recover the account and set a new password. For more information, see Forgot password.

  • Register user

    If enabled, the register user flow initiates actions to create an account for a user. The flow calls the user.register action to create the new user. For more information, see Register user.

  • Sign on with identity provider

    If enabled, the social sign-on flow initiates actions to authenticate the user through an external identity provider. For more information, see Sign on with identity provider.

Sign on with username and password

The username/password branch of the login flow uses the usernamePassword.check action to verify the user’s password. If the user’s password status is OK, the flow transitions to the next action required by the sign-on policy. If the user’s password has expired, the flow transitions to the PASSWORD_EXPIRED flow state. The response from the usernamePassword.check action includes a HAL link to initiate the password.reset action to update the password. If the user is using a temporary password, the flow transitions to the MUST_CHANGE_PASSWORD flow state. The user can initiate the password.reset action to change the temporary password.

Check password

Forgot password

The recover password branch of the login flow uses the user.lookup action to verify the user. After user look-up, the flow transitions to the RECOVERY_CODE_REQUIRED flow state. The flow uses the password.recover action to issue a recovery code to the user. After the recovery code is issued and the user submits the correct code, the flow transitions to the MUST_CHANGE_PASSWORD flow state and uses the password.reset action to update the user’s password.

Recover password

Register user

The register user branch of the login flow initiates the user.register action to create a new user account and set a password. The sign-on screen prompts the user to submit a username, an email address, and a password. If this action executes successfully, the flow transitions to the next action required by the sign-on policy.

Register user

Sign on with identity provider

The external identity provider (social sign-on) branch of the login flow initiates actions to authenticate the user through an external identity provider. It also links the external identity provider to the PingOne user account.

The flow diagram shows a flow path to update a user who already has an existing link to an external identity provider account, bypassing the ACCOUNT_LINKING_REQUIRED flow state. It also shows a flow path if the external identity provider account is not linked to an existing PingOne user. In this case, the flow transitions to the ACCOUNT_LINKING_REQUIRED flow state and calls the user.register action to find a matching user and initiate account linking to the external provider.

External IdP

From the ACCOUNT_LINKING_REQUIRED flow state, a user can either register as a new user or link to an existing PingOne user. In cases where the user does not exist in PingOne, the external identity provider login flow calls the user.register action to register the external identity account user as a new PingOne user. Consequently, when the social sign-on branch is implemented as a sign-on option, the sign-on policy should also include the register user sign-on branch with the registration.​enabled policy action attribute set to true.

If registration is enabled and the user exists in PingOne but no external account link is defined, PingOne tries to find a matching user (usually by email address). If PingOne does not find a matching user, then registration is required. If PingOne finds one or more matching users (more than one user in the system with a matching email address), then the flow prompts for a username and password to verify the user’s identity and complete the account link.

If the registration login flow branch is disabled in the sign-on policy, then the user who tries to log in with external identity provider credentials can only link to an already existing user in PingOne.

Identifier first action

The identity provider discovery login flow initiates actions to identify the user and determine the applicable authentication methods for this user. It is designed to be used as an alternative to the standard login flow. It differs from the username/password login flow in that it first prompts the user for a username, and then it uses the identity provider discovery rules defined in the sign-on policy to route the user to the correct external identity provider for authentication.

A condition in the sign-on policy specifies the external identity providers that are evaluated to verify whether one of them is the authoritative source of identity. If one is found, the user is directed to authenticate using the external identity provider’s authentication flow. The flow transitions to the EXTERNAL_AUTHENTICATION_REQUIRED flow state and redirects the browser to the external identity provider’s login URL.

IdP Discovery

Multi-factor action

The MFA (multi-factor authentication) flow adds an MFA action to authentication flow. The flow transitions to the DEVICE_SELECTION_REQUIRED flow state and calls the device.select action to specify the device used for the MFA action. If an email or SMS device is selected, the flow transitions to the OTP_REQUIRED flow state and calls the otp.check action to send a one-time password (OTP) to the user’s specified device. After the OTP is issued and the user submits the correct OTP, the flow completes.

MFA

Push authentication

This branch of the MFA flow shows the flow states for a push authentication confirmation action (on a mobile device). The flow starts at the DEVICE_SELECTION_REQUIRED flow state and calls the device.select action to specify the device used for the MFA action. If a mobile device is selected, the flow transitions to the PUSH_CONFIRMATION_REQUIRED flow state. If the user taps the APPROVE option, the flow transitions to the COMPLETED flow state. If the user taps the DENY option, the flow transitions to the FAILED flow state.

If the user does not respond to the push authentication confirmation request, the request times out. The flow transitions to the PUSH_CONFIRMATION_TIMED_OUT flow state and uses the device.select action to prompt the user to select a device for the MFA action. The user can retry with the same device or choose another device. If the user chooses to retry with the same device (or with a different mobile device), the flow transitions to the PUSH_CONFIRMATION_REQUIRED flow state. If the user selects an email or SMS device, the flow transitions to the OTP_REQUIRED flow state and uses the otp.check action to complete the MFA sign-on action.

Progressive profiling action

The progressive profiling login flow prompts users to provide additional data at sign on. The attribute data provided is added to the user’s profile. For example, this flow can be configured to follow the user.register action to add more user data to the newly created account. The sign-on screen prompts the user to submit data for the specified user attributes. If this action executes successfully, the flow transitions to the next action required by the sign-on policy.

Progressive profiling