--- title: Configuring the LDAP Username Password Credential Validator description: The LDAP Username password credential validator (PCV) verifies credentials using an organization's LDAP datastore. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_configure_ldap_username_pcv canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_configure_ldap_username_pcv.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: October 13, 2023 section_ids: about-this-task: About this task steps: Steps related-links: Related links --- # Configuring the LDAP Username Password Credential Validator The LDAP Username password credential validator (PCV) *(tooltip: \
\

Configures a centralized location for user credential validation. The validator instances can then be referenced by PingFederate.\

\
)* verifies credentials using an organization's LDAP datastore. ## About this task When an authentication error occurs, PingFederate automatically parses the messages returned by PingDirectory, Microsoft Active Directory (AD), Oracle Unified Directory (OUD), or Oracle Directory Server (ODS) and categorizes them with error conditions. 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. 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 can create custom experiences based on the error responses, which contain the error messages. The HTML Form Adapter uses the relevant error conditions to determine the LDAP password-change scenarios and to present the relevant messages to the end users. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | These customizable messages are stored in the PingFederate message file, `pingfederate-messages.properties`, located in the `/pingfederate/server/default/conf/language-packs` directory.You can localize these messages by using the PingFederate localization framework for an international audience. For more information, see [Localizing messages for end users](pf_local_message_end_users.html). | ## Steps 1. Go to the **Instance Configuration** tab. 2. (Optional) Override the authentication error messages. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You might require this option in order 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 can 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. If you selected **Use Message Properties Key** from the **Error** list, enter an error message string or a defined message properties key. If you selected any other option from the **Error** list, you must leave the **Message Properties Key** field empty. * A unique key name Enter the key for the defined error message you want to return. You can define message keys in the `pingfederate-message.properties` file. Learn more in [Localizing messages for end users](pf_local_message_end_users.html). * 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. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Click **Edit**, **Update**, or **Cancel** to make or undo a change to an existing entry. Click **Delete** or **Undelete** to remove an existing entry or cancel the removal request.Use the up and down arrows to change the display order. The display order does not affect runtime processing. | 3. Select the LDAP datastore and enter information into the required fields. For more information about each field, see 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**. 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. | | **Search Base**(Required) | The location in the directory server from which the search begins. | | **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 can 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}))` To ensure that your service providers (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: Extend the PCV contract and fulfill the subject identifier through the HTML Form Adapter. For more information, see Extending the contract for the credential validator. Add a data source in the SP connection and fulfill the subject identifier through a datastore query. For more information, see Configuring attribute sources and user lookup. If you use authentication policy in conjunction with a policy contract, you can add a data source in the contract mapping configuration and fulfill the subject identifier in an SP connection through the authentication policy contract. For more information, see Applying policy contracts or identity profiles to authentication policies. 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 through 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 incoming user IDs, respectively. | | **Scope of Search** | The level of search to perform 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 default 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 window\.This checkbox is selected by default. | | Advanced fields for self-service password reset, account unlock, and user name 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 user name 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. When configuring in conjunction with user name 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 user name 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. | | **Mail Search Filter**(for user name recovery) | The LDAP query to locate a user record using an email address, such as `mail=${mail}`.This field is required when user name recovery is enabled in any HTML Form Adapter instances that validate credentials against this LDAP Username PCV instance. 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. | | **Username Attribute**(for user name recovery) | The LDAP attribute containing the user identifier of the users.This field is required when user name recovery is enabled in any HTML Form Adapter instances that validate credentials against this LDAP Username PCV instance. This attribute should correspond to the attribute specified on the left side of the Search Filter field. | | **Mail Verified Attribute**(for user name recovery) | The LDAP attribute indicating whether the user's email address is verified. The expected value of this user attribute is either `true` or `false` (case insensitive).This field is required when user name recovery using only verified email addresses is enabled in any HTML Form Adapter instances that validate credentials against this LDAP Username PCV instance. | | **Account Disabled Attribute** | For password reset and account unlock, the boolean LDAP attribute that indicates whether the user's account is disabled. For example, `ds-pwp-account-disabled` is the default PingDirectory attribute. PingFederate doesn't use this field's value when Microsoft Active Directory is the datastore. | | **Enable PingDirectory Detailed Password Policy Requirement Messaging**(for change password and password reset) | For password changes through an LDAP PCV backed by PingDirectory, this option indicates whether PingDirectory should return detailed password policy violations to PingFederate so that the invoking authentication source, namely the HTML Form Adapter, can present them to the end-users. The User DN associated with the selected LDAP Datastore must be granted the proper access control instruction (ACI) in PingDirectory. For more information, see Configuring the password validation details request control ACI. | | **Expect Password Expired Control**(for password expiry) | When selected, PingFederate expects the LDAP datastore to return the password expired control when a user presents valid credentials but their password has expired.PingFederate can use this control in the bind response to distinguish between the following cases:- An expired password with valid credentials - An expired password with invalid credentialsBy default, the checkbox is cleared.When using PingDirectory as the credential store, if a user's password has expired, the following settings ensure PingFederate doesn't direct the user to the Change Password form when they enter an invalid password:- Select the **Expect Password Expired Control** checkbox. - Set the **return-password-expiration-controls** setting in the PingDirectory password policy to **always**. | | **Disabled User Attribute**(for password reset and account unlock) | For password reset and account unlock, the Boolean LDAP attribute that indicates if the user's account is disabled. For example, `'ds-pwp-account-disabled'` is the default PingDirectory attribute name for this field. This attribute name is not used when Microsoft Active Directory is the datastore. | ## Related links * [Configuring an HTML Form Adapter instance](pf_config_html_form_adapt_instance.html)