Rate this page

Account Lookup Authenticator

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

The Account Lookup identity authenticator is used to search for a matching account based on some input value provided by the user. For example, this authenticator may be used to prompt the user to provide an email address corresponding to one belonging to an existing account. The Account Lookup authenticator is typically used in conjunction with another authenticator. For example, it can be used in a password recovery flow along with the reCAPTCHA and email delivered code to securely reset a user’s password.

Field Type Description
status string Indicates the authenticator state. Values are ready, failure, or success.
lookupParameters array An array of strings, consisting of parameters that the Broker will use to search for a matching account. These values are provided by the Auth API based on the Broker configuration. See the discussion below.
error string An error code set by the server after an authentication attempt is made.
errorDetail string A human-readable error description.

Lookup parameters

Lookup parameters are identifiers used to perform a search for a matching user account. The identifiers are extracted from the Account Lookup Identity Authenticator’s Match Filter property in the Data Governance Broker configuration. The match filter is a SCIM search filter that is executed to find a matching account.

For example, if the Account Lookup authenticator is configured with the following match filter:

userName eq "%userId%" or emails.value eq "%emailAddress%"

Then the Auth API will present the following lookup parameters:

{
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "userId",
      "emailAddress"
    ]
  }
}

The auth UI may then prompt the end user for values to provide for the match filter. The lookup parameters names are used as field names when submitting the values to the Broker.

{
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "userId",
      "emailAddress"
    ],
    "userId": "horselover",
    "emailAddress": "horselover@example.com"
  }
}

Authentication

To make a request using the Account Lookup authenticator, the auth UI should set one or more fields corresponding to the available lookup parameters:

{
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "userId",
      "emailAddress"
    ],
    "userId": "horselover",
    "emailAddress": "horselover@example.com"
  }
}

If the account lookup fails, then the status field will be set to failure, and an error code will be provided in the error field:

{
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "userId",
      "emailAddress"
    ],
    "userId": "horselover",
    "emailAddress": "horselover@example.com",
    "status": "failure",
    "error": "noMatch"
  }
}

If the account lookup finds a match, then the status field will be set to success:

{
  "urn:pingidentity:scim:api:messages:2.0:AccountLookupRequest": {
    "lookupParameters": [
      "userId",
      "emailAddress"
    ],
    "userId": "horselover",
    "emailAddress": "horselover@example.com"
  }
}