Common sign-on actions

The flow endpoint is used to interact with the user in a sign-on workflow. Flow endpoint operations are used only to implement custom authentication UIs. OIDC/OAuth 2 and SAML requests initiate the flow and redirect the browser to the custom authentication UI (which is configured in the application through the application’s loginPageUrl property).

Login actions

The flow endpoint can initiate login actions that specify the operations required to authenticate with a username and password.

Multi-factor authentication actions

The flow endpoint can also initiate multi-factor authentication (MFA) actions that specify the operations required to complete authentication using a registered user device and a one-time password (OTP).

Identifier first actions

The flow can initiate a discovery action used to identify the user by username and determine the applicable authentication methods for this user.

Progressive profiling

Progressive profiling actions prompt users to provide additional data at sign on. This action type does not authenticate users. It is used only to obtain additional profile data.

Flow status

In a sign-on workflow, the flow’s status property value returned by the last action identifies the appropriate next action in the authentication process. For example, if an application uses the LOGIN sign-on policy, when a user initiates sign-on and starts the authentication flow, the response returned by the flow shows a status value that specifies the next required step to complete this flow successfully. For the LOGIN sign-on policy, the next action prompts the user to enter a username and password, as indicated by the USERNAME_PASSWORD_REQUIRED value in the status property.

"status" : "USERNAME_PASSWORD_REQUIRED"

The response data includes a HAL link to the required action, which in this case is the usernamePassword.check:

{
  "_links" : {
    "self" : {
      "href" : "https://auth.pingone.com/{environmentId}/flows/{flowID}"
    },
    "session.reset" : {
      "href" : "https://auth.pingone.com/{environmentId}/flows/{flowID}"
    },
    "usernamePassword.check" : {
      "href" : "https://auth.pingone.com/{environmentId}/flows/{flowID}"
    }
  },

After the user submits a username and password, the flow calls the usernamePassword.check action to verify the username and password.

Flow status values

An authentication flow can return one of the following status values in response to a sign-on action:

Flow API operations

The GET /{environmentId}/flows/{flowID} operation retrieves the flow specified by the flowID in the request URL. For more information about this flow action, see Get a flow.

The flow endpoint operation, POST /{environmentId}/flows/{flowID}, supports several flow actions that are specified by the custom media type provided in the HTTP Content-Type request header. The following table lists the PingOne custom media types and their associated authentication flow actions:

For hands-on experience with the flow endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Flows common response data model

These common properties are returned with the flow response.

These common links are returned with the flow response.

These common embedded resources are returned with the flow response:

Response codes

Flow status data model and embedded resources

The following sections show the parameters required by the flow status. In addition, the following links and embedded resources are returned in the flow response for the given flow status.

USERNAME_PASSWORD_REQUIRED

SIGN_ON_REQUIRED

PASSWORD_REQUIRED

PASSWORD_EXPIRED

MUST_CHANGE_PASSWORD

RECOVERY_CODE_REQUIRED

VERIFICATION_CODE_REQUIRED

DEVICE_SELECTION_REQUIRED

OTP_REQUIRED

PUSH_CONFIRMATION_REQUIRED

ACCOUNT_LINKING_REQUIRED

EXTERNAL_AUTHENTICATION_REQUIRED

PROFILE_DATA_REQUIRED

Endpoint examples

Get a flow

The GET /{environmentId}/flows/{flowID} operation retrieves information about a flow specified by the flow ID in the request URL.

curl -X GET \
  'https://auth.pingone.com/{environmentId}/flows/{flowID}' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: ST=<sessionToken>'

The status property in the response specifies the next action in the authentication flow. The response data looks like this:

{
  "_links" : {
    "self" : {
      "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    },
    "usernamePassword.check" : {
      "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    },
    "user.register" : {
      "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    },
    "password.forgot" : {
      "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    }
  },
  "id" : "ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6",
  "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",
  "_embedded" : {
    "passwordPolicy" : {
      "excludesProfileData" : true,
      "notSimilarToCurrent" : true,
      "excludesCommonlyUsed" : true,
      "maxRepeatedCharacters" : 2,
      "minUniqueCharacters" : 5,
      "length" : {
        "min" : 8,
        "max" : 255
      },
      "minCharacters" : {
        "abcdefghijklmnopqrstuvwxyz" : 1,
        "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : 1,
        "1234567890" : 1,
        "~!@#$%^&*()-_=+[]{}|;:,.<>/?" : 1
      },
      "history" : {
        "count" : 6,
        "retentionDays" : 365
      }
    },
    "socialProviders" : [ {
      "id" : "179a9005-6f26-4294-9388-fcb0e9323353",
      "name" : "Facebook",
      "type" : "FACEBOOK",
      "_links" : {
        "authenticate" : {
          "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/rp/authenticate?providerId=179a9005-6f26-4294-9388-fcb0e9323353&flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
        }
      }
    } ]
  }
}

For a status value of USERNAME_PASSWORD_REQUIRED, the response includes the following HAL links to initiate the possible next operation in the flow, depending on the sign-on policy configuration:

• usernamePassword.check

An action to authenticate with a username and password.

• user.register

  An action to register a new user.

• password.forgot

  An action to recover a user’s forgotten password.

• authenticate

  An action to sign on using an external authentication provider.

Log in with external authentication

PingOne supports login integration between external identity providers (such as Facebook) and PingOne authentication flows. For example, if Facebook is specified as an external identity provider, users have the ability to sign on to their PingOne account using their Facebook credentials and Facebook’s account sign-on flow.

When external authentication is enabled, the flow initialization response includes the socialProviders embedded resource, which provides the following information about each external identity provider that can be used by the user to sign on:

"socialProviders" : [ {
  "id" : "179a9005-6f26-4294-9388-fcb0e9323353",
  "name" : "Facebook",
  "type" : "FACEBOOK",
  "_links" : {
    "authenticate" : {
      "href" : "https://auth.pingone.com/4fda72e8-0490-4e2a-96ba-2b0a4cf25ddd/rp/authenticate?providerId=179a9005-6f26-4294-9388-fcb0e9323353&flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    }
  }
} ]

The authenticate HAL link can be used to redirect the browser to initiate authentication with the associated external identity provider.

Log in with username and password

When the flow status is USERNAME_PASSWORD_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides an action to allow users to login with a username and password. The request body requires the username and password attributes. The values for these properties provided by the user are verified in this action. This operation uses the application/vnd.pingidentity.usernamePassword.check+json custom media type as the content type in the request header.

If there is a user already associated with the current flow, and a username value is provided in the request body, then the value of username must identify the user associated with the session.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.usernamePassword.check+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "username": "<username>",
    "password": "<password>"
}'

The status property value in the response determines the next action in the flow. The following sample response shows a status value of OTP_REQUIRED, which indicates that the one-time password validation step used in a multi-factor authentication flow is a required action. The otp.check HAL link to initiate this required step is also included in the response.

{
  "_links": {
    "self": {
      "href": "https://auth.pingone.com/{environmentId}/flows/{flowID}"
    },
    "session.reset": {
      "href": "https://auth.pingone.com/{environmentId}/flows/{flowID}"
    },
    "otp.check": {
      "href": "https://auth.pingone.com/{environmentId}/flows/{flowID}"
    }
  },
  "id": "7b37d3e8-38b0-4469-b553-04b8bee08e6f",
  "resumeUrl": "https://auth.pingone.com/{environmentId}/as/resume?flowId={flowID}",
  "status": "OTP_REQUIRED",
  "requiredStep": {
    "id": "1a03bd20-4348-4b40-a4f9-e5a0c629aae1"
  },
  "selectedDevice": {
    "id": "341762d5-22c4-bdf3-3417-62d522c4bdf3"
  },
  "createdAt": "2018-09-20T13:40:56.977Z",
  "expiresAt": "2018-09-20T13:56:12.306Z",
  "_embedded": {
    "devices": [
      {
        "id": "341762d5-22c4-bdf3-3417-62d522c4bdf3",
        "environment": {
          "id": "{environmentId}"
        },
        "type": "EMAIL",
        "email": "jo****@pingidentity.com",
        "user": {
          "id": "482a626f-a894-485d-b9f3-ba8f4ed0c58d"
        }
      }
    ],
    "user": {
      "id": "482a626f-a894-485d-b9f3-ba8f4ed0c58d",
      "username": "johndoe",
      "name": {
        "given": "John",
        "family": "Doe"
      }
    }
  }
}

Log in with a username

When the flow status is SIGN_ON_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides an action to allow users to sign on with a username. The request body requires only the username attribute. The username value is verified in this action. This operation uses the application/vnd.pingidentity.user.lookup+json custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.user.lookup+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "username": "<username>"
}'

Forgot password

When the flow status is RECOVERY_CODE_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides an action to recover a user’s forgotten password. The request body requires the username attribute to identify the user and send a one-time password (OTP) that is used to set a new password. This operation uses the application/vnd.pingidentity.password.forgot+json custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.password.forgot+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "username": "<value>"
}'

Register a user

When the flow status is USERNAME_PASSWORD_REQUIRED or ACCOUNT_LINKING_REQUIRED, the POST /{environmentId}/flows/{flowId} operation initiates an action to register a user. For USERNAME_PASSWORD_REQUIRED, the request body requires the username, email, and password attributes to define a new user. This operation uses the application/vnd.pingidentity.user.register+json custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.user.register+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "username": "user1",
    "email": "user1@pingidentity.com",
    "password": "<password>"
}'

Check password

When the flow status is USERNAME_PASSWORD_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides an action to prompt the user who has previously signed on with a username and password to verify the password again. The request body requires the password attribute. However, the sign-on flow could prompt for the username value if the username does not match the user currently associated with the session. This operation uses the application/vnd.pingidentity.usernamePassword.check+json custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.usernamePassword.check+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "username": "user1",
    "password": "<password>"
}'

Reset password

When the flow status is PASSWORD_EXPIRED or MUST_CHANGE_PASSWORD, the POST /{environmentId}/flows/{flowId} operation provides an action to change (or reset) the user’s password. The request body requires the currentPassword and newPassword attributes. This operation uses the application/vnd.pingidentity.password.reset+json custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.password.reset+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "currentPassword": "<current password>",
    "newPassword": "<new password>"
}'

Recover password

When the flow status is RECOVERY_CODE_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides an action to recover the account and set a new password. The request body requires the recoveryCode and newPassword attributes. This operation uses the application/vnd.pingidentity.password.recover+json custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.password.recover+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "recoveryCode": "<code>",
    "newPassword": "<new password>"
}'

Send recovery code

When the flow status is VERIFICATION_CODE_REQUIRED, the POST /{environmentId}/flows/{flowId} operation sends a new verification email if the user lost or did not receive their previous email. The OTP in the verification email is a randomly generated eight-character alphanumeric string, and the code is valid for five minutes. This operation uses the application/vnd.pingidentity.password.sendRecoveryCode custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.password.sendRecoveryCode' \
  -H 'Cookie: ST=<sessionToken>' \
}'

Verify user

When the flow status is VERIFICATION_CODE_REQUIRED, the POST /{environmentId}/flows/{flowId} operation initiates an action to verify the user account to continue the authentication flow. The user must click the link in the verification email to verify the account. The request body requires the verificationCode attribute identifying the verification code to check. This operation uses the application/vnd.pingidentity.user.verify+json custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.user.verify+json' \
  -H 'Cookie: ST=<sessionToken>' \
  -d '{
    "verificationCode": "<new password>"
}'

Send verification email

When the flow status is VERIFICATION_CODE_REQUIRED, if the user did not receive the verification email, the POST /{environmentId}/flows/{flowId} operation provides an action to send the user a new account verification email. This operation uses the application/vnd.pingidentity.user.sendVerificationCode+json custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowId}' \
  -H 'Content-Type: application/vnd.pingidentity.user.sendVerificationCode+json' \
  -H 'Cookie: ST=<sessionToken>' \
}'

Select an MFA device

PingOne supports email and SMS-capable device types for use in a multi-factor authentication flow. To enable multi-factor authentication, a user resource must have a device ID associated with its user ID.

When the flow status is DEVICE_SELECTION_REQUIRED or PUSH_CONFIRMATION_REQUIRED, the POST /{environmentId}/flows/{flowId} operation provides an action to specify a device ID to use in the multi-factor authentication flow. This operation uses the application/vnd.pingidentity.device.select+json custom media type as the content type in the request header.

curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}" \
-H 'Content-type: application/vnd.pingidentity.device.select+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
  "device": {
    "id": "<deviceId>"
  }
}'

Validate the OTP

When the flow status is OTP_REQUIRED, the multi-factor authentication flow uses a one-time password (OTP) sent to the user’s device to continue the login flow. The user receives the OTP and submits it as a step in the login process. The MFA actions service validates the OTP to complete the authentication flow.

The following sample shows the POST /{environmentId}/flows/{flowId} operation to validate the OTP used in the multi-factor authentication flow. This operation uses the application/vnd.pingidentity.otp.check+json custom media type as the content type in the request header.

curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}" \
-H 'Content-type: application/vnd.pingidentity.otp.check+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
  "otp": "<otp>"
}'

Submit profile data

In an authentication flow, users can be prompted to add data to their profile. When the flow status is PROFILE_DATA_REQUIRED, the POST /{environmentId}/flows/{flowId} operation uses the application/vnd.pingidentity.user.update+json custom media type as the content type in the request header.

curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}" \
-H 'Content-type: application/vnd.pingidentity.user.update+json' \
-H 'Cookie: ST=<sessionToken>' \
-d '{
  "email": "lindajones@ping.com",
  "address": {
    "postalCode": "78613"
  }
}
'

Reset a flow

The following sample shows the POST /{environmentId}/flows/{flowID} operation that updates (or resets) a flow session. This operation uses the application/vnd.pingidentity.session.reset+json custom media type as the content type in the request header.

curl -X POST \
  'https://auth.pingone.com/{environmentId}/flows/{flowID}' \
  -H 'Content-Type: application/vnd.pingidentity.session.reset+json' \
  -H "Cookie: ST=<sessionToken>"