Flow orchestration service

Flow orchestration

The flow orchestration service configures the steps required to authenticate the requestor that initiated the authentication request. The service is responsible for initiating the authentication session and includes the step service, which calls specific actions required by the authentication workflow.

Login actions

The flow orchestration service includes login actions that specify the operations required to authenticate with a username and password.

Multi-factor authentication actions

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

Flow orchestration API operations

The flow orchestration service supports the following endpoint operations:

POST Create a flow
POST Update a flow
GET Read a flow
DELETE Delete a flow
GET Read a login step
POST Validate password
PUT Change a user password
GET Read an MFA step
POST Select an MFA device
POST Validate the one-time password

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

Flow orchestration data model

Property	Description
`application.id`	A string that specifies the identifier of the resource referenced by this relationship.
`authenticators`	The set of authenticators that must be completed interactively in this flow.
`completedSignOnPolicy.id`	A string that specifies the identifier of the resource referenced by this relationship.
`completedSignOnPolicy.name`	A string that specifies the display name of the resource referenced by this relationship.
`createdAt`	The time the resource was created.
`environment.id`	A string that specifies the identifier of the resource referenced by this relationship.
`expiresAt`	The time this flow will expire due to inactivity timeout based on a sliding window.
`id`	A string that specifies the resource’s unique identifier.
`maxSecondsSinceLastSignOn`	A string that specifies the .
`prop`	An integer that specifies the maximum number of seconds since the session’s `lastSignOn.at` time to wait before triggering policy actions to re-authenticate the user. When set to 0, policy actions are always triggered.
`relayState`	An identifier for the resource that the user is redirected to after login.
`request.http.remoteIp`	A string that specifies the remote IP of the request that initiated the flow.
`request.http.userAgent`	A string that specifies the user agent of the request that initiated the flow.
`request.requestProperties`	A string that specifies the user agent of the request that initiated the flow.
`requiredStep`	A string that specifies the identifier of the resource referenced by this relationship.
`resumeUrl`	A string that specifies where the flow handler UI will redirect the browser to after flow is `COMPLETED` or `FAILED`.
`session.id`	A string that specifies the identifier of the resource referenced by this relationship.
`signOnPolicies.id`	A string that specifies the identifier of the resource referenced by this relationship.
`signOnPolicies.name`	A string that specifies the display name of the resource referenced by this relationship.
`status`	A string that specifies the status of the flow. Options are `COMPLETED`, `FAILED`, or `STEP_REQUIRED`.
`user.id`	A string that specifies the identifier of the resource referenced by this relationship.

Property	Description
`action.id`	A string that specifies the identifier of the resource referenced by this relationship.
`action.type`	A string that specifies the type of the resource referenced by this relationship.
`currentPassword`	A string that specifies the user’s current password.
`flow.id`	A string that specifies the identifier of the resource referenced by this relationship.
`id`	A string that specifies the resource’s unique identifier.
`newPassword`	A string that specifies the user’s new password…
`password`	A string that specifies the password used to authenticate.
`status`	A string that specifies the status of the action. Action services can use any value except `COMPLETED`, which is reserved and meaningful to the flow orchestration service.
`username`	A string that specifies the username used to authenticate.

Multi-factor authentication actions data model

Property	Description
`action.id`	A string that specifies the identifier of the resource referenced by this relationship.
`action.type`	A string that specifies the type of the resource referenced by this relationship.
`currentPassword`	A string that specifies the user’s current password.
`device.id`	A string that specifies the device resource’s unique identifier.
`flow.id`	A string that specifies the identifier of the resource referenced by this relationship.
`id`	A string that specifies the resource’s unique identifier.
`otp`	A string that specifies the one-time password.
`selectedDevice.id`	A string that specifies the identifier of the resource referenced by this relationship.
`status`	A string that specifies the status of the action. Action services can use any value except `COMPLETED`, which is reserved and meaningful to the flow orchestration service.

Response codes

Code	Message
200	Successful operation.
201	Successfully created.
204	Successfully removed. No content.
400	The request was invalid.
401	You weren’t authenticated to perform this operation.
404	The specified object doesn’t exist.

Endpoint examples

Create a flow

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/{envID}/flows/' \
  -H "Content-type: application/json" \
  -d "{
   "signOnPolicies": [
      "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": "<state>",
    "redirectUri": "https://client.example.org/cb",
    "nonce": "3904lksjbh"
  },
  "resumeUrl": "https://domain/oidc/resumeAuthorize",
}"

Update a flow

The following sample shows the POST /{environmentId}/flows/{flowID} operation that updates (or resets) a flow orchestration 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' \

Get a flow

You can use the GET /{environmentId}/flows/{flowID} operation to retrieve 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' \

The response data looks like this:

{
  "_links":{
    "self": {
      "href": "https://auth.pingone.com/{envId}/flows/<flowId>"
    },
    "usernamePassword.check": {
      "href": "/flows/123/steps/<stepId>"
    },
    "user.register": {
      "href": "/flows/123/steps/<stepId>"
    },
    "recoveryOtp.send": {
      "href": "/flows/123/steps/<stepId>"
    },
    "external.login": {
      "href": "/flows/123/steps/<stepId>"
    }

    "requiredStep": {
      "href": "https://auth.pingone.com/{envId}/flows/<flowId>/steps/<stepId>"
    }
  },
  "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": "USERNAME_PASSWORD_REQUIREDSTEP_REQUIRED",
  "requiredStep": {
    "id": "<stepId>"
  },
  "expiresAt": "2018-01-26T19:04:17Z",
  "_embedded": {
    "providers": [
      {
        "id": "...",
        "name": "Facebook",
        "icon": "..."
      },
      {
        "id": "...",
        "name": "Twitter",
        "icon": "..."
      }
    ]
    "requiredStep": {
        "_links": {
          "self": {
            "href": "https://domain/api/vi/environments/{envId}/flows/<flowId>/steps/<stepId>"
          },
          "validatePassword": {
            "href": "https://domain/api/vi/environments/{envId}/flows/<flowId>/steps/<stepId>/password"
          }
        },
        "id": "<stepId>",
        "action": {
          "id": "<actionId>",
          "type": "Local Authentication"
        },
        "status": "LOGIN_REQUIRED",
        "lastUsername": "bob@example.com"
      }
  }
}

Delete a flow

You can use the GET /{environmentId}/flows/{flowID} operation to delete the flow specified by the flow ID in the request URL.

curl -X DELETE \
  'https://auth.pingone.com/{environmentId}/flows/{flowID}' \
  -H 'Content-Type: application/json'

For successful delete operations, a 204 NO CONTENT message is returned by the request.

The following sample shows the GET /environments/{environmentId}/flows/{flowId}/steps/{stepId} operation to return information about the flow orchestration step specified by its ID in the request URL.

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

The response data looks like this for a password check step:

{
  "_links": {
    "usernamePassword.check": {
      "href": "'https://auth.pingone.com/environments/{environmentId}/flows/{flowId}/steps/{stepId}"
    },
    "password.forgot": {
      "href": "'https://auth.pingone.com/environments/{environmentId}/flows/{flowId}/steps/{stepId}"
    }
  },
  "status": "USERNAME_PASSWORD_REQUIRED",
}

Validate-password

You can use the POST /environments/{environmentId}/flows/{flowId}/steps/{stepId} operation to initiate an action step to verify the username and password used in an authentication flow. 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.

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

Change password

You can also use the POST /environments/{environmentId}/flows/{flowId}/steps/{stepId} operation to initiate an action step to change 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/environments/{environmentId}/flows/{flowId}/steps/{stepId}' \
  -H 'Content-Type: application/vnd.pingidentity.password.reset+json' \
  -d '{
    "currentPassword": "<current password>",
    "newPassword": "<new password>"
}'

Read-an-MFA-step

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

The response data looks like this for an MFA device step:

Need response data

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.

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. 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}/steps/{stepId}/device" \
-H "Content-type: application/vnd.pingidentity.device.select+json" \
-d "{
  "device": {
    "id": "<deviceId>"
  }
}"

Validate the OTP

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} 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}/steps/{stepId}" \
-H "Content-type: application/vnd.pingidentity.otp.check+json" \
-d "{
  "otp": "123456"
}"

Flow orchestration service