Rate this page

Password Recovery Account Flow

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

The Password Recovery flow is a special flow that can be used to reset an end user’s password.

The Password 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 Password Recovery flow by requesting the URI contained within the passwordRecovery 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:PasswordRecoveryRequest.
meta complex always By default, will contain a resourceType sub-attribute with the value Password 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 complex 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. Examples might include the end user’s username, full name, or icon. 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.
passwordRequirements array An array of password requirements objects, indicating the rules that must be satisfied before a new password will be accepted.
newPassword string A new password for the user. This must be provided before the flow can be satisfied.

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

Here is an example Password Recovery flow message:

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:PasswordRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Password Recovery",
    "location": "https://example.com/authentication/account/Password%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. Unlike other flows, the auth UI must also provide a proposed new password in the newPassword field before the flow will complete. This is illustrated by the following example:

Example: Password recovery

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

Example password 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.
  5. The auth UI must submit a new password to the server.

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:PasswordRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Password Recovery",
    "location": "https://example.com/authentication/account/Password%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"
  },
  "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"
  }
}

The Auth API will respond by setting the success flags of the reCAPTCHA and Account Lookup authenticators to true. Notice that password requirements will also be provided.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:PasswordRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Password Recovery",
    "location": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "success": false,
  "passwordRequirements": [
    {
      "type": "length",
      "description": "The password must contain at least 6 characters.",
      "minPasswordLength": "6"
    },
    {
      "type": "notCurrentPassword",
      "description": "The new password must not be the same as the current password."
    }
  ],
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "identifier": "horselover.fat",
    "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 at the email address associated with the account.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:PasswordRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Password Recovery",
    "location": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "success": false,
  "passwordRequirements": [
    {
      "type": "length",
      "description": "The password must contain at least 6 characters.",
      "minPasswordLength": "6"
    },
    {
      "type": "notCurrentPassword",
      "description": "The new password must not be the same as the current password."
    }
  ],
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "identifier": "horselover.fat",
    "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
  }
}

Once the user provides the verification code to the auth UI, it can submit the verification code, along with the user’s new password.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:PasswordRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Password Recovery",
    "location": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "success": false,
  "passwordRequirements": [
    {
      "type": "length",
      "description": "The password must contain at least 6 characters.",
      "minPasswordLength": "6"
    },
    {
      "type": "notCurrentPassword",
      "description": "The new password must not be the same as the current password."
    }
  ],
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "identifier": "horselover.fat",
    "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"
  },
  "newPassword": "vastActiveLivingIntelligenceSystem"
}

If the password change is accepted, then the flow’s success flag will be set to true.

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AccountFlow:PasswordRecoveryRequest"
  ],
  "meta": {
    "resourceType": "Password Recovery",
    "location": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
  },
  "followUp": {
    "type": "login",
    "$ref": "https://example.com/authentication/login/ARH5F9B..."
  },
  "success": true,
  "passwordRequirements": [
    {
      "type": "length",
      "description": "The password must contain at least 6 characters.",
      "minPasswordLength": "6"
    },
    {
      "type": "notCurrentPassword",
      "description": "The new password must not be the same as the current password."
    }
  ],
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "identifier"
    ],
    "identifier": "horselover.fat",
    "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.