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 service endpoints 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 to complete all sign-on actions, and if required, it calls the multi-factor authentication (MFA) action service to complete all MFA actions needed to authenticate the requestor and return an access token.

Flow orchestration

The flow orchestration service is responsible for initiating the authentication session and managing actions specified by the custom authentication workflow.

Sign-on action states

Sign-on actions specify the operations required to authenticate with a username and password. The flow orchestration service supports operations to engage the login action service to complete the following login actions:

  • User registration
  • Password check
  • Password reset
  • Password recovery

Multi-factor authentication action states

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 flow orchestration service supports operations to engage the MFA service to complete the following MFA actions:

  • Select a device for MFA authentication
  • Check the 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 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 actions are completed, the authorization service resumes control of the flow to generate and return 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 Activity - Using PingOne authentication 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:

curl -X POST \
  'https://auth.pingone.com/{environmentID}/flows/' \
  -H 'Content-type: application/json' \
  -d '{
    "application": {
        "id": ""
    },
    "request": {
        "http": {
            "remoteIp": "someIp",
            "userAgent": "someUserAgent"
        },
        "requestProperties": {
            "foo": "bar"
        },
        "oidc": {
            "responseType": [
                "code"
            ],
            "scopes": [
                "openid",
                "profile",
                "email"
            ]
        }
    },
    "resumeUrl": "http://localhost:8081/?flowId={flowId}",
    "relayState": {
        "state": "<state>",
        "redirectUri": "http://www.mlk.com",
        "nonce": "
    },
    "#signOnPolicies": [
        {
            "name": "Multi_Factor"
        },
        {
            "name": "Custom"
        }
    ],
    "#user": {
        "id": ""
    }
}'

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 'Cookie: ST=<sessionToken>'

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' \
-H 'Cookie: ST=<sessionToken>' \
-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' \
-H 'Cookie: ST=<sessionToken>' \
-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' \
-H 'Cookie: ST=<sessionToken>' \
-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 'Cookie: ST=<sessionToken>' \

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. This operation uses the application/vnd.pingidentity.device.select+json custom media type as the content type in the request header.

The following sample shows the POST /{environmentId}/flows/{flowId}/steps/{stepId} 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}" \
-H 'Content-type: application/vnd.pingidentity.device.select+json' \
-H 'Cookie: ST=<sessionToken>' \
-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. This operation uses the application/vnd.pingidentity.otp.check+json custom media type as the content type in the request header.

The following sample shows the POST /{environmentId}/flows/{flowId}/steps/{stepId} operation to validate the OTP used in the multi-factor authentication flow:

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