Activity - Configure a custom authentication user interface


Introduction

For organizations that host the authentication user interface (UI) on their domain server, the PingOne flow orchestration and step services are used as the building blocks to enable authorization and authentication for the custom UI.

When an authorization request is received, it is redirected to the PingOne authorization server, which then calls the PingOne flow orchestration service to begin the authentication workflow. The flow orchestration service calls the login action service, and if required, the multi-factor authentication (MFA) action service to authenticate the requestor and return an access token.

The following diagram shows the flow orchestration steps and actions for a custom authentication UI flow.

API Model

Flow orchestration steps

The flow orchestration service configures and runs the steps to complete the client authentication request. The flow orchestration service is responsible for initiating the authentication session and managing all steps and actions specified by the custom authentication workflow.

Login actions

Login actions specify the operations required to authenticate with a username and password. This service provides endpoints to get information about a particular login action by its step ID, validate username and password input, and change a user’s password within the login flow.

Multi-factor authentication actions

Multi-factor authentication (MFA) actions specify the operations required to complete authentication using a registered user device and a one-time password (OTP). PingOne supports email and SMS-capable device types for use in a multi-factor authentication flow. To enable multi-factor authentication, the user resource must have a device associated with its user ID. The MFA action service provides endpoints to get information about a particular MFA action by its step ID, specify a device to use in the multi-factor authentication flow, and validate the one-time password (OTP) used in the authentication flow.

Authentication workflow overview

To create a custom authentication flow, the following tasks must be completed successfully:

  1. After receiving an authorization request, the flow orchestration service initiates the authentication session and calls the login action service to initiate login.
  2. The flow orchestration service gets the flow state, retrieving the step state from the login action service.
  3. The user interacts with the login action UI, which calls the flow orchestration service to proxy requests to the login action service.
  4. The login action service interacts with the directory service to validate the username and password. It sends responses back to the UI through the flow orchestration service.
  5. The MFA action service is called by the flow orchestration service. In a multi-factor authentication flow, users are prompted to enter the OTP sent to the user’s specified device. The MFA action UI calls the flow orchestration service to proxy requests to the MFA action service. The MFA action service validates the OTP submitted by the user, and it sends the response back to the UI through the flow orchestration service.
  6. After all action steps are completed, the authorization service resumes control of the flow to generate and returns an access token.

Note: Calls to the login and MFA action service are unauthenticated requests. You do not need an assigned role to execute login action service operations. These requests are proxied through the flow orchestration service, which does not require permission.

For more information about the PingOne out-of-box authentication flow, see Work with flows.

Flow orchestration endpoints

You can initiate the authentication session and specify the sign-on policies, scopes, required steps, and other properties for the flow. The following sample shows the POST /{environmentId}/flows operation to start the flow:

POST https://auth.pingone.com/{environmentId}/flows HTTP/1.1
Content-type: application/json
Authorization: Bearer jwtToken

{
  "_links" : {
    "self" : { "href" : "https://auth.pingone.com/{environmentId}/flows" }
  },
 "application": {
   "id": "<string>"
 },
 "authenticators": [
   "<string>"
 ],
 "completedSignOnPolicy": {
   "id": "<string>",
   "name": "<string>"
 },
 "environment": {
   "id": "<string>"
 },
 "relayState": {
   "state": "af0ifjsldkj",
   "redirectUri": "https://client.example.org/cb",
   "nonce": "3904lksjbh"
 },
 "request": {
   "http": {
     "remoteIp": "string",
     "userAgent": "string"
   },
   "requestProperties": {
     "additionalProp1": {
     }
   }
},
 "resumeUrl": "https://domain/oidc/resumeAuthorize",
 "requiredStep": {
   "id": "<string>"
 },
 "resumeUrl": "<string>",
 "session": {
   "id": "string"
 },
 "signOnPolicies": [
   {
     "id": "string",
     "name": "string"
   }
 ],
 "status": "COMPLETED",
 "user": {
   "id": "string"
 }
}

This request returns a 201 Created message and sets the session cookie. The response data shows the property values specified in the request body and the HAL links to required steps defined in the custom flow. The following shows sample response data:

201 Created
Set-Cookie: ST=abcd; Secure; HttpOnly; Expires=..
Location: /{envId}/flows/<flowId>
{
  "_links":{
    "self": {
      "href": "https://auth.pingone.com/{environmentId}/flows/<flowId>"
    },

    "requiredStep": {
      "href": "https://auth.pingone.com/{environmentId}/flows/<flowId>/steps/<stepId>"
    },
    "requiredUi": {
      "href": "https://apps.pingone.com/login?environmentId=<envId>&flowId=<flowId>"
    }
  },
  "id": "<flowId>",
   "signOnPolicies": [
    {
      "id": "<policyId>"
      "name": "MFA"
    },
  ],
  "client":{
    "id": "<clientId>"
  },
  "request":{
    "oidc": {
      "responseType": [
        "code"
      ],
      "scopes": [
        "openid",
        "profile",
        "email"
      ]
    },
    "http": {
      "remoteIp": "4.4.4.4",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/604.4.7 (KHTML, like Gecko) Version/11.0.2 Safari/604.4.7”
    }
  },
  "relayState": {
    "state": "af0ifjsldkj",
    "redirectUri": "https://client.example.org/cb",
    "nonce": "3904lksjbh"
  },
  "resumeUrl": "https://domain/oidc/resumeAuthorize",
  "status": "STEP_REQUIRED",
  "requiredStep": {
    "id": "<stepId>"
  },
  "expiresAt": "2018-01-26T19:04:17Z",
  "_embedded": {
    "requiredStep": {
        "_links": {
          "self": {
            "href": "https://domain/api/vi/environments/{environmentId}/flows/<flowId>/steps/<stepId>"
          },
          "validatePassword": {
            "href": "https://domain/api/vi/environments/{environmentId}/flows/<flowId>/steps/<stepId>/password"
          }
        },
        "id": "<stepId>",
        "action": {
          "id": "<actionId>",
          "type": "Local Authentication"
        },
        "status": "LOGIN_REQUIRED",
        "lastUsername": "bob@example.com"
      }
  }
}

Login actions endpoints

You can get a specific step in the login action flow by specifying the flow ID and the step ID in the request URL. The following sample shows the GET /{environmentId}/flows/{flowId}/steps/{stepId} operation to return a specified login step from a specified flow:

curl -X GET "https://auth.pingone.com/{environmentId}/flows/{flowId}/steps/{stepId}" \
-H "Content-type: application/json"

The request URL contains the following required parameter values:

  • environmentId

    Specifies the environment resource associated with the login flow.

  • flowId

    Specifies the ID of the login flow associated with associated environment.

  • stepId

    Specifies the ID of an identified action within the login flow.

Validate password endpoint

When a user requests authorization to access PingOne services, the flow orchestration service calls the POST /{environmentId}/flows/{flowId}/steps/{stepId} endpoint in the login action service to validate the username and password submitted by the user. This operation uses the application/vnd.pingidentity.usernamePassword.check+json custom media type as the content type in the request header when there is no user associated with the current flow. The operation uses the application/vnd.pingidentity.password.check+json custom media type as the content type in the request header when there is a user associated with the current flow. The following sample shows the operation to validate the username and password submitted during the authentication flow:

curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}/steps/{stepId}" \
-H "Content-type: application/vnd.pingidentity.usernamePassword.check+json" \
-d "{
  "username": "jameslymanstone",
  "password": "ChangeM3!"
}"

The following sample shows the operation to validate the password submitted by a user during the authentication when the username property is already associated with the current flow:

curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}/steps/{stepId}" \
-H "Content-type: application/vnd.pingidentity.password.check+json" \
-d "{
  "password": "CheckM3!"
}"

Update password endpoint

If a user cannot authenticate because of an expired or invalid password, the flow orchestration service calls the login actions service to update the password within the context of the authentication flow. The PUT /{environmentId}/flows/{flowId}/steps/{stepId} initiates the password update operation. This operation uses the application/vnd.pingidentity.password.reset+json custom media type as the content type in the request header.

curl -X PUT "https://auth.pingone.com/{environmentId}/flows/{flowId}/steps/{stepId}/password" \
-H "Content-type: application/vnd.pingidentity.password.reset+json" \
-d "{
  "currentPassword": "ChangeM3!",
  "newPassword": "A-New-Passw0rD!"
}"

Multi-factor authentication actions endpoints

You can get a specific step in the MFA action flow by specifying the flow ID and the step ID in the request URL. The following sample shows the GET /{environmentId}/flows/{flowId}/steps/{stepId} operation to return a specified MFA step from a specified flow:

curl -X GET "https://auth.pingone.com/{environmentId}/flows/{flowId}/steps/{stepId}" \
-H "Content-type: application/json"

The request URL contains the following required parameter values:

  • environmentId

    Specifies the environment resource associated with the authentication flow.

  • flowId

    Specifies the ID of the authentication flow associated with associated environment.

  • stepId

    Specifies the ID of an identified MFA action within the authentication flow.

Device identification endpoint

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.

The following sample shows the POST /{environmentId}/flows/{flowId}/steps/{stepId}/device operation to specify a device ID to use in the multi-factor authentication flow:

curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}/steps/{stepId}/device" \
-H "Content-type: application/json" \
-d "{
  "device": {
    "id": "<deviceId>"
  }
}"

One-time password validation endpoint

The multi-factor authentication flow uses a one-time password (OPT) 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}/steps/{stepId}/otp operation to validate the OTP used in the multi-factor authentication flow:

curl -X POST "https://auth.pingone.com/{environmentId}/flows/{flowId}/steps/{stepId}/otp" \
-H "Content-type: application/json" \
-d "{
  "otp": "123456"
}"