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 A 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, 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 email address.
codeRequested boolean A flag set by the auth UI, indicating whether or not a verification code should be sent to the end user’s email address.
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 email addresses

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

For information about validating email addresses, see the Validated Email Addresses SCIM API and Second factor authentication preferences articles.

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

{
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "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: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"
  }
}