Rate this page

Telephony Delivered Code Authenticator

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

The Telephony Delivered Code authenticator sends a temporary verification code to an end user’s phone number, expecting the same verification code to be submitted back to the server via the auth UI. This is most often used as a second authentication factor.

Actual delivery of the verification code is handled by a messaging provider such as Twilio. Multiple messaging providers may be configured and presented to the end user as options. For example, a Twilio SMS messaging provider could be configured to send SMS text messages, while a Twilio voice messaging provider could be delivered to send messages via an automated voice system.

This authenticator is invoked in stages. In the first step, the auth UI requests that the Broker deliver a temporary verification code to the end user’s phone number. In the second step, the auth UI submits the verification code back to the server.

Field Type Description
status string Indicates the authenticator state. Values are unavailable, ready, failure, or success.
attributeValue string An obscured string, representing the phone number that will be used to deliver a verification code to the end user. The auth UI may choose to display this value to the end user.
codeSent boolean A flag set by the Data Governance Broker, indicating whether or not a verification code has been sent to the end user’s phone number.
deliverCode complex An object describing the message to be sent to the end user. Its fields are described in the table below.
messagingProvider string The name of the messaging provider to be used to deliver the verification code. This corresponds to the name of a Telephony Messaging Provider in the Data Governance Broker configuration.
verifyCode string A verification code to submit for confirmation. This is provided by the end user.
error string An error code set by the server after an authentication attempt is made.
errorDetail string A human-readable error description.

The deliverCode object has the following fields:

Field Type Description
message string The message to deliver to the end user. This must contain a %code% placeholder string for the verification code.
language string The language and locale of the message. An example value is en-US.

Authentication

In its initial state, the Telephony Delivered Code authenticator will show a status of ready if it can be used for the current user. The attributeValue field will contain an obscured phone number, which the auth UI may display to the end user.

{
  "urn:pingidentity:scim:api:messages:2.0:TelephonyDeliveredCodeAuthenticationRequest": {
    "attributeValue": "5********5",
    "codeSent": false,
    "status": "ready"
  }
}

Deliver one-time verification code to user

To send a verification code, the auth UI should set the deliverCode.message and deliverCode.language fields. The deliverCode.message field must include a %code% placeholder variable, into which the Broker will interpolate the verification code.

{
  "urn:pingidentity:scim:api:messages:2.0:TelephonyDeliveredCodeAuthenticationRequest": {
    "attributeValue": "5********5",
    "codeSent": false,
    "status": "ready",
    "deliverCode": {
      "message": "Please provide the following code to complete authentication: %code%",
      "language": "en-US"
    }
  }
}

After the server delivers the verification code message, it will respond by setting the codeSent value to true. Be aware that the status field will be set to failure. This is an indication that this authenticator’s authentication state is in progress.

{
  "urn:pingidentity:scim:api:messages:2.0:TelephonyDeliveredCodeAuthenticationRequest": {
    "attributeValue": "5********5",
    "codeSent": true,
    "status": "failure"
  }
}

Submit one-time verification code to authentication service

When the end user receives the verification code via SMS or voice message, he or she should submit it to the auth UI, which then provides it to the Broker in the verifyCode field.

If the verification code is rejected, the server will not change the status field.

{
  "urn:pingidentity:scim:api:messages:2.0:TelephonyDeliveredCodeAuthenticationRequest": {
    "attributeValue": "5********5",
    "codeSent": true,
    "status": "failure",
    "verifyCode": "807216"
  }
}

If the verification code is accepted, the server will set the status field to success.

{
  "urn:pingidentity:scim:api:messages:2.0:TelephonyDeliveredCodeAuthenticationRequest": {
    "attributeValue": "5********5",
    "codeSent": true,
    "status": "success"
  }
}