An authentication workflow starts with an application’s sign-on policy. The sign-on policy determines the steps and corresponding actions required to authenticate a user’s account. When the authentication workflow begins, the flow gets the sign-on policy (or policies) assigned to the application.
The PingOne platform includes the following two pre-configured sign-on policies:
Single_Factor
A single-factor sign-on policy that prompts users to enter a username and password to authenticate the account.
Multi_Factor
A two-step authentication process that prompts users to take the following actions to authenticate the account:
If an application does not have an assigned sign-on policy, it uses the default sign-on policy for the environment. If the application has one or more assigned sign-on policies, the flow service evaluates the sign-on policies and their conditions based on designated priority (or the order in which the assigned policies are listed in the acr_values attribute of the authorization request). If all actions for an assigned policy complete successfully, the authorization workflow completes successfully.
For more information about sign-on policies, see Sign-on policies and Sign-on policy actions.
For information about assigning a sign-on policy to an application, see Sign-on policy assignments.
PingOne authentication workflows are initiated with a call to the /{{envID}}/as/authorize endpoint. The application’s type property determines the parameters required in the authorize request. For more information about application types and the supported parameters for an authorize request, see Authorization requests for application types.
The response to an /{{envID}}/as/authorize request returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID for this specific authentication workflow. The user’s browser is redirected to the sign-on screen, which looks like this for a new session.
For an existing session, the user’s browser is redirected to a sign-on screen that prompts for a password:
As the user’s browser is redirected to the sign-on screen, the PingOne Authorize service calls the GET /{{envID}}/flows/{{flowID}} operation and uses the {{flowID}} value from the /{{envID}}/as/authorize response to get the flow and the current flow state. The status property in the GET /{{envID}}/flows/{{flowID}} response specifies the initial flow state, which determines the possible next actions in the authentication workflow.
Both the Single_Factor and Multi_Factor pre-defined sign-on policies require a username and password. The response data looks like this:
{
"_links": {
"self": {
"href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
},
"usernamePassword.check": {
"href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
},
"password.forgot": {
"href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
}
},
"id": "663067c8-3973-4578-adf2-f42514fe3dc1",
"resumeUrl" : "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/as/resume?flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6",
"status" : "USERNAME_PASSWORD_REQUIRED",
"createdAt" : "2019-06-04T21:52:34.866Z",
"expiresAt" : "2019-06-04T22:07:35.724Z"
}
}In this example, the status attribute shows a flow state of USERNAME_PASSWORD_REQUIRED, specifying that username and password values are required to complete this sign-on action. The response also includes the following links to present options for the next operation in the flow:
usernamePassword.check
An action to sign on with a username and password.
password.forgot
A sign-on action to recover a user’s forgotten password.
To respond to the USERNAME_PASSWORD_REQUIRED flow state, the user initiates the usernamePassword.check action, which includes these steps:
The user enters a username and password in the fields provided on the sign-on screen.
The user clicks Sign on to initiate the usernamePassword.check authentication action.
The flow service calls the POST /{{envID}}/flows/{{flowID}} endpoint operation and uses the application/vnd.pingidentity.usernamePassword.check+json custom media type in the Content-type HTTP request header to identify the action. For more information about this request, see Login with username and password.
For a Single_Factor sign-on policy, if the user’s account and password are valid, the flow returns a status of COMPLETED, indicating that the conditions of the Single_Factor sign on policy have been met.
The response data looks like this:
{
"_links": {
"self": {
"href": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
}
},
"id": "663067c8-3973-4578-adf2-f42514fe3dc1",
"session": {
"id": "ec249037-9f42-40d5-bdda-eb9b7ddeac18"
},
"resumeUrl": "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/as/resume?flowId=663067c8-3973-4578-adf2-f42514fe3dc1",
"status": "COMPLETED",
"createdAt": "2019-07-09T19:56:59.817Z",
"expiresAt": "2019-07-09T20:22:08.229Z",
"_embedded": {
"user": {
"id": "710d6278-ccce-4a91-bdb9-ac7a4a0e60d5",
"username": "lindajones@example.com",
"name": {
"given": "Linda",
"family": "Jones"
}
}
}
}For a Multi_Factor sign-on policy, after the username/password action finishes, the flow continues by returning one of the following MFA status values:
DEVICE_SELECTION_REQUIRED
This flow state prompts the user to select a device to receive the OTP. This status occurs when the user has more than one registered device.
OTP_REQUIRED
This flow state prompts the user to complete a multi-factor authentication action that involves receiving a one-time password (OTP) on a specified device and submitting the OTP. This status occurs when the user has only one EMAIL, SMS or VOICE registered device used to receive the OTP (or after selecting a device).
PUSH_CONFIRMATION_REQUIRED
This flow state prompts the user to approve or deny a push confirmation sent to the user’s registered native device. This status occurs when the user has only one registered MOBILE device type registered to receive push notifications (or after selecting a native device).
PUSH_CONFIRMATION_TIMED_OUT
This flow state occurs when the user does not respond to the push authentication confirmation request. It prompts the user to retry push authentication (with the same device) or choose a different registered device.
The MFA authentication flow requires specific actions depending on the flow state.
To respond to the DEVICE_SELECTION_REQUIRED flow state, the user initiates the device.select action, which includes these steps:
The sign-on screen presents the list of registered devices.
The user clicks a registered device to specify the device to use for the MFA action.
The flow service calls the POST /{{envID}}/flows/{{flowID}} endpoint operation and uses the application/vnd.pingidentity.device.select+json custom media type in the Content-type HTTP request header to identify the action. For more information about this request, see Select an MFA device.
After a device is selected, the flow transitions to the OTP_REQUIRED flow state and initiates the otp.check action, or it transitions to the PUSH_CONFIRMATION_REQUIRED flow state to prompt the user to accept or deny the confirmation request.
To respond to the OTP_REQUIRED flow state, the user initiates the otp.check action, which includes these steps:
The user receives the OTP on the specified device.
The user enters the OTP in the field provided on the sign-on screen.
The user clicks Submit to initiate the otp.check authentication action.
The flow service calls the POST /{{envID}}/flows/{{flowID}} endpoint operation and uses the application/vnd.pingidentity.otp.check+json custom media type in the Content-type HTTP request header to identify the action. For more information about this request, see Validate the OTP.
After the OTP is issued and the user submits the correct OTP, the flow completes.
To respond to the PUSH_CONFIRMATION_REQUIRED flow state, the user completes these actions:
The user receives the push authentication request on the specified native device.
The user chooses ACCEPT or DENY in response to the confirmation prompt.
Validation for a push authentication request is managed by the PingOne Native SDK on the native device. For more information, see Native SDK APIs.
To respond to the PUSH_CONFIRMATION_TIMED_OUT flow state, the user completes these actions:
The user is prompted to either retry push authentication on the currently selected device, or select a different registered native device.
For a retry action, the user receives the push authentication request on the currently selected native device and chooses APPROVE or DENY in response to the confirmation prompt.
Validation for a push authentication request is managed by the PingOne Native SDK on the native device.
For a Multi_Factor sign-on policy, if the user submits the correct OTP or selects APPROVE in the push confirmation prompt, the flow returns a status of COMPLETED, indicating that the conditions of the Single_Factor sign on policy have been met.
For more information about MFA flow states, see Multi-factor authentication flow states.