Rate this page

Username Password Authenticator

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

The Username Password identity authenticator handles conventional authentication using a username and password. This authenticator should be used with the Login flow.

When an authentication request is received through this authenticator, the Data Governance Broker sends an LDAP BIND request to the Ping Identity Directory Server acting as the user store. The result of the request will be indicated by the status field.

Field Type Description
status string Indicates the authenticator state. Values are unavailable, ready, failure, or success.
passwordExpiring boolean A flag indicating that the user’s password is expiring soon.
usernameRecovery complex A reference to the Username Recovery account flow handler.
passwordRecovery complex A reference to the Password Recovery account flow handler.
username string The end user’s username. Set by the auth UI.
password string The end user’s password. Set by the auth UI.
newPassword string A new password to set for the end user. This field should only be provided after an error is returned with the value mustChangePassword.
passwordRequirements array An array of password quality requirement objects, described below. This field is only present after an error is returned with the value mustChangePassword.
error string An error code. Returned if an authentication attempt fails. The most common error code is invalidCredentials.

Both the usernameRecovery and passwordRecovery objects contain the following fields:

Field Type Description
type string The name of the account flow handler. Typical values are “Username Recovery” or “Password Recovery”, but these may be changed by the Broker administrator.
$ref string The URI of the account flow. The auth UI should perform a GET of this URI to transition to the desired account flow.

Password quality requirements

Password quality requirements are sets of rules enforced by the user store when changing a user’s password. These correspond to password validators in a Ping Identity Directory Server’s configuration.

Password quality requirement objects will always contain the type and description fields. Other fields may be present, depending on the type.

Field Type Description
type string The type of password requirement. See the table below.
description string A human-readable description of the password requirement.
requirementSatisfied boolean Whether or not a proposed password satisfied this password requirement. This field only appears in password change error responses.
additionalInfo string A human-readable message explaining why a password change attempt failed. This field only appears in password change error responses.

Possible password requirement types include:

Password requirement type Description
notCurrentPassword The current password may not be reused.
history A new password cannot match a password in the user’s password history.
attributeValue The password value must not be present in another attribute of the user.
characterSet The password must contain at least a specified number of characters from one or more character sets defined by the password requirement.
haystack The password must satisfy a configurable requirement based upon the password haystacks concept.
length The password must meet a minimum/maximum length requirement.
regularExpression The password must match a configured regular expression.
repeatedCharacters The password may not contain a configured number of consecutive characters.
similarity The password must be sufficiently dissimilar to the current password.
uniqueCharacters The password must contain a minimum number of unique characters.

The user store may also be configured with custom password requirements with other type values.

Authentication

To make an authentication request using the Username Password authenticator, the auth UI should set the username and password fields:

{
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "passwordExpiring": false,
    "usernameRecovery": {
      "type": "Username Recovery",
      "$ref": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
    },
    "passwordRecovery": {
      "type": "Password Recovery",
      "$ref": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
    },
    "status": "ready",
    "username": "horselover",
    "password": "password"
  }
}

If the authentication attempt is rejected by the user store, then the authenticator’s status field will be set to failure:

{
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "username": "horselover",
    "passwordExpiring": false,
    "usernameRecovery": {
      "type": "Username Recovery",
      "$ref": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
    },
    "passwordRecovery": {
      "type": "Password Recovery",
      "$ref": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
    },
    "status": "failure",
    "error": "invalidCredentials"
  }
}

If the authentication attempt is accepted by the user store, then the authenticator’s status field will be set to success:

{
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "username": "horselover",
    "passwordExpiring": false,
    "usernameRecovery": {
      "type": "Username Recovery",
      "$ref": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
    },
    "passwordRecovery": {
      "type": "Password Recovery",
      "$ref": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
    },
    "status": "success"
  }
}

Forced Password Change

In some cases, a password policy configured at the user store may require that an end user change his or her password in order to complete a login. When this happens, the Username Password authenticator will respond to an authentication attempt with a status of failure and an error code of mustChangePassword. If the user store imposes any password rules, then those will be listed in the passwordRequirements field.

{
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "username": "horselover",
    "passwordExpiring": 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."
      }
    ],
    "usernameRecovery": {
      "type": "Username Recovery",
      "$ref": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
    },
    "passwordRecovery": {
      "type": "Password Recovery",
      "$ref": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
    },
    "status": "failure",
    "error": "mustChangePassword"
  }
}

The auth UI should prompt the end user at this point for both the current password and a proposed new password. If any password requirements exist, the auth UI can indicate those to the user.

The auth UI then submits the current and new passwords to the Auth API.

{
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "username": "horselover",
    "password": "current-password",
    "newPassword": "new-password",
    "passwordExpiring": 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."
      }
    ],
    "usernameRecovery": {
      "type": "Username Recovery",
      "$ref": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
    },
    "passwordRecovery": {
      "type": "Password Recovery",
      "$ref": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
    },
    "status": "failure",
    "error": "mustChangePassword"
  }
}

If the proposed new password is rejected by the user store, then the authenticator’s status field will be set to failure, and error will be set to invalidNewPassword.

The passwordRequirements field will include additional information about the reason for the password change failure. Any password requirements that were not satisfied will have a requirementSatisfied value set to false, and an additionalInfo message will be provided for display to the user.

{
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "username": "horselover",
    "passwordExpiring": false,
    "passwordRequirements": [
      {
        "type": "length",
        "requirementSatisfied": true,
        "description": "The password must contain at least 6 characters.",
        "minPasswordLength": "6"
      },
      {
        "type": "notCurrentPassword",
        "requirementSatisfied": false,
        "description": "The new password must not be the same as the current password.",
        "additionalInfo": "The provided new password cannot be the same as the current password or any password in the password history."
      }
    ],
    "usernameRecovery": {
      "type": "Username Recovery",
      "$ref": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
    },
    "passwordRecovery": {
      "type": "Password Recovery",
      "$ref": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
    },
    "status": "failure",
    "error": "invalidNewPassword"
  }
}

If the proposed new password is accepted by the user store, then the authenticator’s status field will be set to success:

{
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "username": "horselover",
    "passwordExpiring": false,
    "usernameRecovery": {
      "type": "Username Recovery",
      "$ref": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
    },
    "passwordRecovery": {
      "type": "Password Recovery",
      "$ref": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
    },
    "status": "success"
  }
}