Rate this page

Second Factor Flow

Schema URN
urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest

The Second Factor authentication flow is used to provide additional assurance about the identity of a user who has already authenticated through the Login flow.

This flow is not necessarily executed for every user. Whether a user is required to provide a second authentication factor is largely determined by the Broker’s policies.

Field Type Provided? Description
schemas array always The SCIM schema of the flow. Always has the value urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest.
meta complex always Will always contain a resourceType sub-attribute with the value secondFactor. Will always contain a location sub-attribute with the current flow URI.
followUp complex always An object indicating the authorization endpoint URI to be retrieved when this flow is complete. Will always contain a type sub-attribute and a $ref sub-attribute; the latter is the URI to be retrieved.
sessionIdentityResource complex If an end user is already logged in, the sub-attributes of this object are attribute values of the user that may be displayed by the auth UI. Examples might include the end user’s username, full name, or icon. The attributes included here are determined by the Session Resource Attribute property of the Broker’s Authentication Service configuration.
client complex always Describes the OAuth 2 client that initiated the current authentication process. Will always contain the name sub-attribute, which is the display name of the client. Will contain a description sub-attribute for the client if one is available.
success boolean Will be present with a value of true if the flow’s enforcement criteria have been satisfied.

In addition to the fields above, objects representing any identity authenticators associated with the Second Factor flow in the Broker configuration will be listed in a Second Factor flow message.

Here is an example Second Factor flow message. Note that there are three identity authenticators listed, one of which is not available for use with the current user, as indicated by its status of unavailable.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest"
  ],
  "meta": {
    "resourceType": "secondFactor",
    "location": "https://example.com/authentication/secondFactor/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "urn:pingidentity:scim:api:messages:2.0:TOTPAuthenticationRequest": {
    "status": "ready"
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": false,
    "status": "ready"
  },
  "urn:pingidentity:scim:api:messages:2.0:TelephonyDeliveredCodeAuthenticationRequest": {
    "codeSent": false,
    "status": "unavailable"
  }
}

Example: Emailed OTP authentication

The auth UI typically arrives at the Second Factor Flow after following the URI in the followup response received after completing the Login Flow.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest"
  ],
  "meta": {
    "resourceType": "secondFactor",
    "location": "https://example.com/authentication/secondFactor/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": false,
    "status": "ready"
  }
}

The auth UI begins by requesting that the Broker deliver a one-time password (OTP) to the end user’s email address. This is done by setting the messageSubject and messageText fields of the Email Delivered Code authenticator.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest"
  ],
  "meta": {
    "resourceType": "secondFactor",
    "location": "https://example.com/authentication/secondFactor/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": false,
    "status": "ready",
    "messageSubject": "Your one-time password code",
    "messageText": "Your one-time code is: %code%"
  }
}

The Auth API responds by setting codeSent to true.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest"
  ],
  "meta": {
    "resourceType": "secondFactor",
    "location": "https://example.com/authentication/secondFactor/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "success": false,
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": true,
    "status": "failure"
  }
}

The auth UI should now prompt the user to enter the one-time password. Once the end user does so, the auth UI can submit the code for verification in the verifyCode field.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest"
  ],
  "meta": {
    "resourceType": "secondFactor",
    "location": "https://example.com/authentication/secondFactor/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "success": false,
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": true,
    "verifyCode": "797764",
    "status": "failure"
  }
}

If the verification succeeds and no other authenticators are required by the Login flow, then the flow’s success flag will be set to true.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest"
  ],
  "meta": {
    "resourceType": "secondFactor",
    "location": "https://example.com/authentication/secondFactor/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Horselover Fat",
    "userName": "horselover"
  },
  "success": true,
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": true,
    "status": "success"
  }
}

At this point, the auth UI should make a GET request of the followup URI to proceed to the next flow.