The LDAP Username Password Credential Validator (PCV) verifies credentials using an organization's LDAP datastore.

When an authentication error occurs, PingFederate automatically parses the messages returned by PingDirectory, Microsoft Active Directory (AD), Oracle Unified Director (OUD), or Oracle Directory Server (ODS) and categorize them with the following error conditions:

  • Account disabled
  • Account expired
  • Account locked
  • Attribute value invalid
  • Attribute conflict
  • Invalid credentials
  • Invalid telephone number
  • Not permitted to logon at this time
  • Not permitted to logon at this workstation
  • Password expired
  • Password policy violated
  • Please try again later
  • User already exists
  • User must reset password
  • User not found

As needed, and when validating against a directory server other than PingDirectory, AD, OUD, or ODS, administrators can define custom message categorization by mapping specific error messages (with wildcard support) to the desired error conditions on the Instance Configuration screen.

The error messages are returned to the HTML Form Adapter instances and the OAuth clients using the Resource Owner Password Credential grant type. The HTML Form Adapter is designed to show the error message it receives from the LDAP Username PCV. OAuth-client developers may create custom experiences based on the error responses, which contain the error messages. The HTML Form Adapter also uses the relevant error conditions to determine the LDAP password-change scenarios and to present the relevant messages to the end users.

Tip:

These customizable messages are stored in the PingFederate message file, pingfederate-messages.properties, located in the <pf_install>/pingfederate/server/default/conf/language-packs directory.

As needed, you may localize these messages by using the PingFederate localization framework for an international audience (see Localizing messages for end users).

On the Instance Configuration screen, configure per-instance settings that suit your use cases.

  1. Optional: Override authentication error messages.
    Note:

    This option may be required for a directory server other than PingDirectory, AD, OUD, or ODS to support the password change function in the HTML Form Adapter or to alter the end-user messages associated with that function.

    1. Click Add a new row to 'Authentication Error Overrides'.
    2. Enter an applicable LDAP error message under Match Expression.

      You may use wildcard asterisks (*) to match messages returned from your directory server; for example: *expired*

    3. Select a relevant error condition from the Error list.
    4. Optional: Enter a key name or an error message under Message Properties Key.
      No value

      If you skip this field, PingFederate returns the default message based on the selected error condition.

      A unique key name

      If you enter a key name in this field and then add the key name with a key value (the desired error message) to the PingFederate message file, PingFederate returns that key value.

      The key name must be unique. Furthermore, you may localize these messages by using the PingFederate localization framework for an international audience.

      An error message

      If you enter an error message in this field (without defining it in the PingFederate message file), PingFederate returns your message verbatim.

    5. Click Update under Action.
    6. Repeat these steps to add more overrides as needed.

    Use the Edit, Update, and Cancel workflow to make or undo a change to an existing entry. Use the Delete and Undelete workflow to remove an existing entry or cancel the removal request.

    Use the up and down arrows to change their display order. The display order does not affect runtime processing.

  2. Select the LDAP datastore and enter information into the required fields.
    For more information about each field, refer to the following table:
    Field Description
    LDAP Datastore

    (Required)

    		 The LDAP datastore configured in PingFederate.

    If you have not yet configured the server to communicate with the directory server you need, click Manage Data Stores.

    Note:

    When connecting to an AD LDAP server, if you want to enable the password changes, password reset, or account unlock features in the HTML Form Adapter, you must secure the datastore connection to your AD LDAP server using LDAPS; AD requires this level of security to allow password changes.

    There is no default selection.

    Search Base

    (Required)

    		 The location in the directory server from which the search begins.

    This field has no default value.

    Search Filter

    (Required)

    		 The LDAP query to locate a user record.

    If your use case requires the flexibility of allowing users to identify themselves using different attributes, you may include these attributes in your query. For instance, the following search filter allows users to sign on using either the sAMAccountName or employeeNumber attribute value through the HTML Form Adapter:

    (|(sAMAccountName=${username})(employeeNumber=${username}))

    Important:

    To ensure that your SPs always get the expected attribute, select a specific user attribute as the source of the subject identifier when configuring the applicable SP connections. There are several ways to do so:

    Similarly, when configuring multifactor authentication using PingID® , where you chain an instance of the PingID Adapter behind an HTML Form Adapter instance, ensure that you also select a specific user attribute as the incoming user attribute for the PingID Adapter instance. For example, if you have set up PingFederate as the identity bridge for your PingOne® for Enterprise account and have selected sAMAccountName as the subject identifier in the SP connection, you should also select sAMAccountName as the incoming user attribute for your PingID Adapter instance. You can accomplish this via an instance of the Composite Adapter or an authentication policy. For more information, see Input User ID Mapping in Configuring a Composite Adapter instance or Incoming User ID in Specifying an incoming user ID, respectively.

    This field has no default value.

    Scope of Search The level of search to be performed in the search base.

    One Level indicates a search of objects immediately subordinate to the base object, not including the base object itself. Subtree indicates a search of the base object and the entire subtree within the base object distinguished name.

    The deault selection is Subtree.

    Case-Sensitive Matching The option to enable case-sensitive matching between the LDAP error messages returned from the directory server and the Match Expression values specified on this screen.

    This check box is selected by default.

    Advanced fields for self-service password reset, account unlock, and username recovery through the HTML Form Adapter
    Display Name Attribute The LDAP attribute used for personalizing messages to the users.

    This field is applicable for all password reset types (other than None), account unlock, and username recovery.

    The default value is displayName.

    Mail Attribute

    (for password reset)

    		 The LDAP attribute containing the email address of the users.

    This field is required when password reset using one-time link or one-time password is enabled in any HTML Form Adapter instances that validate credentials against this LDAP Username PCV instance.

    Note:

    When configuring in conjunction with username recovery, this attribute should correspond to the attribute specified on the left side of the Mail Search Filter field.

    The default value is mail.

    SMS Attribute

    (for password reset)

    		 The LDAP attribute containing the telephone number of the users.

    This field is required when password reset using text message is enabled in any HTML Form Adapter instances that validate credentials against this LDAP Username PCV instance.

    This field has no default value.

    PingID Username Attribute

    (for password reset)

    		 The LDAP attribute containing the PingID username of the users.

    This field is required when password reset using PingID is enabled in any HTML Form Adapter instances that validate credentials against this LDAP Username PCV instance.

    This field has no default value.

    Mail Search Filter

    (for username recovery)

    		 The LDAP query to locate a user record using an email address; for example:

    mail=${mail}

    This field is required when username recovery is enabled in any HTML Form Adapter instances that validate credentials against this LDAP Username PCV instance.

    Note:

    When configuring in conjunction with password reset, the attribute specified on the left side of this search filter should correspond to the attribute specified in the Mail Attribute field.

    This field has no default value.

    Username Attribute

    (for username recovery)

    		 The LDAP attribute containing the user identifier of the users.

    This field is required when username recovery is enabled in any HTML Form Adapter instances that validate credentials against this LDAP Username PCV instance.

    Note:

    This attribute should correspond to the attribute specified on the left side of the Search Filter field.

    This field has no default value.

    Mail Verified Attribute

    (for username recovery)

    		 The LDAP attribute indicating whether the user's email address has been verified. The expected value of this user attribute must either be true or false (case insensitive).

    This field is required when username recovery using only verified email addresses is enabled in any HTML Form Adapter instances that validate credentials against this LDAP Username PCV instance.

    This field has no default value.