Rate this page

Email Delivered Code Authenticator

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

The Email Delivered Code authenticator sends a temporary verification code to an end user’s email address, expecting the same verification code to be submitted back to the server via the auth UI. This is most often used as a second factor or to verify a new user account.

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 email address. 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 email address 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 email address.
messageSubject string The subject of the email message to deliver to the end user. Either this field or messageText must contain a %code% placeholder string for the verification code.
messageText string The body of the email message to deliver to the end user. Either this field or messageSubject must contain a %code% placeholder string for the verification code.
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.

Authentication

In its initial state, the Email 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 email address, which the auth UI may display to the end user.

{
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": false,
    "status": "ready"
  }
}

Deliver one-time verification code to user

To send a verification code, the auth UI should set the messageSubject and messageText fields. One of the fields must include a %code% placeholder variable, into which the Broker will interpolate the verification code.

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

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:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": true,
    "status": "failure"
  }
}

Submit one-time verification code to authentication service

When the end user receives the verification code via email, 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:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "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:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": true,
    "status": "success"
  }
}