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:
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.
Forgot password
If enabled, the recover password flow initiates actions to recover the account and set a new 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.
Sign on with identity provider
If enabled, the social sign-on flow initiates actions to authenticate the user through an external identity provider.
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.
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.
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.
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.
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.