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.

Application sign-on policies

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:

  • Enter a username and password.
  • Enter a one-time password (OTP) on a registered phone number or email, or approve the authentication on a registered native device.

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.

Sign-on request

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:

Get the flow

As the user’s browser is redirected to the sign-on screen, the 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/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
        },
        "usernamePassword.check": {
            "href": "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
        },
        "password.forgot": {
            "href": "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
        }
    },
    "id": "663067c8-3973-4578-adf2-f42514fe3dc1",
    "resumeUrl" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/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 HAL 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.

Complete the sign-on action

To respond to the USERNAME_PASSWORD_REQUIRED flow state, the user initiates the usernamePassword.check action, which includes these steps:

1. The user enters a username and password in the fields provided on the sign-on screen.

2. The user clicks Sign on to initiate the usernamePassword.check authentication action.

3. 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.

Complete the Single_Factor sign-on flow

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/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/663067c8-3973-4578-adf2-f42514fe3dc1"
        }
    },
    "id": "663067c8-3973-4578-adf2-f42514fe3dc1",
    "session": {
        "id": "ec249037-9f42-40d5-bdda-eb9b7ddeac18"
    },
    "resumeUrl": "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/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"
            }
        }
    }
}

Continue the flow for Multi_Factor authentication

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.

  

Complete the MFA action

The MFA authentication flow requires specific actions depending on the flow state.

DEVICE_SELECTION_REQUIRED

To respond to the DEVICE_SELECTION_REQUIRED flow state, the user initiates the device.select action, which includes these steps:

1. The sign-on screen presents the list of registered devices.

2. The user clicks a registered device to specify the device to use for the MFA action.

3. 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.

OTP_REQUIRED

To respond to the OTP_REQUIRED flow state, the user initiates the otp.check action, which includes these steps:

1. The user receives the OTP on the specified device.

2. The user enters the OTP in the field provided on the sign-on screen.

3. The user clicks Submit to initiate the otp.check authentication action.

4. 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.

PUSH_CONFIRMATION_REQUIRED

To respond to the PUSH_CONFIRMATION_REQUIRED flow state, the user completes these actions:

1. The user receives the push authentication request on the specified native device.

2. The user chooses ACCEPT or DENY in response to the confirmation prompt.

3. Validation for a push authentication request is managed by the PingOne Native SDK on the native device. For more information, see Native SDK APIs.

PUSH_CONFIRMATION_TIMED_OUT

To respond to the PUSH_CONFIRMATION_TIMED_OUT flow state, the user completes these actions:

1. The user is prompted to either retry push authentication on the currently selected device, or select a different registered native device.

2. 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.

3. 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.