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 A 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, and this value may be obfuscated, depending on the server configuration.
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.
codeRequested boolean A flag set by the auth UI, indicating whether or not a verification code should be sent to the end user’s phone number.
language string An optional language and locale of the message to be sent. The default value is en-US.
messagingProvider string The optional 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. If not provided, then the first messaging provider configured for the authenticator will be used. If the authenticator is configured to require a validated phone number, then this field is ignored, and the messaging provider that was used to validate the phone number will always be used.
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.

About validated and unvalidated phone numbers

This authenticator may be configured by the administrator to require the use of a validated phone number. This is a phone number that has been previously confirmed to belong to the user.

For information about validating phone numbers, see the Validated Phone Numbers SCIM API and Second factor authentication preferences articles.

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 add a codeRequested field with a value of true.

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

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"
  }
}