Rate this page

Username Recovery Account Flow

Schema URN
urn:pingidentity:scim:api:messages:2.0:AccountFlow:UsernameRecoveryRequest

The Username Recovery flow is a special flow that can be used to recover an end user’s username, given some identifying input from the user, such as an email address or phone number.

The Username Recovery flow is intended to be used in conjunction with the Account Lookup identity authenticator. To prevent abuse, this should also be combined with other authenticators, such as the reCAPTCHA authenticator and the Email Delivered Code authenticator.

The auth UI arrives at the Username Recovery flow by requesting the URI contained within the usernameRecovery object of an Username Password identity authenticator.

Field Type Provided? Description
schemas array always The SCIM schema of the flow. Always has the value urn:pingidentity:scim:api:messages:2.0:AccountFlow:UsernameRecoveryRequest.
meta complex always By default, will contain a resourceType sub-attribute with the value Username Recovery. Will always contain a location attribute with the current flow URI.
followUp complex always An object indicating the authentication flow URI to be retrieved in order to resume authentication. Will always contain a type sub-attribute and a $ref sub-attribute; the latter is the URI to be retrieved.
sessionIdentityResource object 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. The attributes included here are determined by the Session Resource Attribute property of the Broker’s Authentication Service configuration.
success boolean Will be present with a value of true if the flow’s enforcement criteria have been satisfied.
username string The end user’s username. This field is provided by the Auth API upon success.

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

Here is an example Username Recovery flow message:

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:UsernameRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Username Recovery",
    "location": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "status": "ready"
  },
  "urn:pingidentity:scim:api:messages:2.0:RecaptchaAuthenticationRequest": {
    "recaptchaKey": "6LcZ9CETAAAAACpuPrcVuDMZGi6ux6_Of2ePyq6g",
    "status": "ready"
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h***********************t@e***********m",
    "codeSent": false,
    "status": "ready"
  }
}

As with other flows, the auth UI must authenticate using the identity authenticators in the flow, as required by the flow’s authentication chain configuration.

Example: Username recovery

In this example, the Username Recovery account flow handler is configured with the authentication chain depicted in the following image:

Example username recovery authentication chain configuration

This configuration implies the following interaction:

  1. The user must first solve a reCAPTCHA challenge.
  2. The user must then successfully look up an account.
  3. The auth UI must deliver a verification code to the user via email.
  4. The user must submit the correct verification code back to the server via the auth UI.

Nothing prevents the auth UI from submitting a reCAPTCHA response and an account lookup request at the same time, so it should do that, as in the following request.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:UsernameRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Username Recovery",
    "location": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "status": "ready",
    "identifier": "horselover.fat@example.com"
  },
  "urn:pingidentity:scim:api:messages:2.0:RecaptchaAuthenticationRequest": {
    "recaptchaKey": "6LcZ9CETAAAAACpuPrcVuDMZGi6ux6_Of2ePyq6g",
    "status": "ready",
    "recaptchaResponse": "03AHJ_Vuu4RRl8_..."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h**************t@e*********m",
    "codeSent": false,
    "status": "ready"
  }
}

If the provided lookup parameter value matches, the Auth API will respond by setting the success flags of the reCAPTCHA and Account Lookup authenticators to true.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:UsernameRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Username Recovery",
    "location": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "success": false,
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "identifier": "horselover.fat@example.com",
    "status": "success"
  },
  "urn:pingidentity:scim:api:messages:2.0:RecaptchaAuthenticationRequest": {
    "status": "success",
    "recaptchaResponse": "03AHJ_Vuu4RRl8_..."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h**************t@e*********m",
    "codeSent": false,
    "status": "failure",
    "error": "badRequest",
    "errorDetail": "No new code was requested nor was a verify code supplied"
  }
}

Next, the auth UI uses the Email Delivered Code authenticator to send the end user a verification code.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:UsernameRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Username Recovery",
    "location": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "success": false,
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "identifier": "horselover.fat@example.com",
    "status": "success"
  },
  "urn:pingidentity:scim:api:messages:2.0:RecaptchaAuthenticationRequest": {
    "status": "success",
    "recaptchaResponse": "03AHJ_Vuu4RRl8_..."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h**************t@e*********m",
    "codeSent": true,
    "status": "failure",
    "codeRequested": true
  }
}

If the user can receive email at the account belonging to the desired username, then he or she will receive a verification code. Once the user provides the verification code to the auth UI, it can submit the verification code to the Auth API by setting the verifyCode field of the Email Delivered Code authenticator.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:UsernameRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Username Recovery",
    "location": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "success": false,
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "identifier": "horselover.fat@example.com",
    "status": "success"
  },
  "urn:pingidentity:scim:api:messages:2.0:RecaptchaAuthenticationRequest": {
    "status": "success",
    "recaptchaResponse": "03AHJ_Vuu4RRl8_..."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h**************t@e*********m",
    "codeSent": true,
    "status": "failure",
    "verifyCode": "011872"
  }
}

If the verification code is accepted, then the flow’s success flag will be set to true. The end user’s recovered username will be provided in the username field.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:UsernameRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Username Recovery",
    "location": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "success": true,
  "username": "horselover.fat",
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "identifier": "horselover.fat@example.com",
    "status": "success"
  },
  "urn:pingidentity:scim:api:messages:2.0:RecaptchaAuthenticationRequest": {
    "status": "success",
    "recaptchaResponse": "03AHJ_Vuu4RRl8_..."
  },
  "urn:pingidentity:scim:api:messages:2.0:EmailDeliveredCodeAuthenticationRequest": {
    "attributeValue": "h**************t@e*********m",
    "codeSent": true,
    "status": "success"
  }
}

To return to the original authentication flow, the auth UI should make a GET request for the followup URI.