Authentication flow states


Authentication workflow states

An application’s sign-on policy determines 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 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 flows and flow states

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). For a multi-factor authentication flow, 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.

The following sections provide flow diagrams and descriptions of the sign-on actions required to complete the authentication flow.

Login flow

A new session login flow that transitions to the USERNAME_PASSWORD_REQUIRED flow state specifies that a username and password is required to complete the flow.

Login new session

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

  • Check password

    The check password flow verifies the password submitted by the user through the sign-on screen. For more information, see Check password flow states.

  • Recover password

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

  • 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 flow states.

Check password flow states

The check 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

Recover password flow states

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 flow states

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

External identity provider login flow states

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.

Multi-factor authentication flow states

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 flow states

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.