PingFederate Server

Configuring the LDAP Username Password Credential Validator

The LDAP Username password credential validator (PCV) 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 <pf_install>/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.

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. 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.

    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:

    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 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 window.

    This check box 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.

    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 credentials

    By 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.