PingFederate offers self-service user name recovery for users to recover their account in the event of forgotten user name via email.

When enabled, a user who forgot their user name can recover it by providing an email address. If PingFederate can locate the user record using such email address, PingFederate sends to the user at the provided address an email message containing the recovered user name. If the email ownership verification status is stored as part of the user record in the directory server, it is also possible to restrict the delivery of user name recovery email messages to users who have proven ownership of their email addresses.

This optional capability is integrated into the HTML Form Adapter and the LDAP Username Password Credential Validator (PCV). PingFederate supports PingDirectory, Microsoft Active Directory, Oracle Unified Directory, and Oracle Directory Server out-of-the-box. Custom PCV implementations may also be developed to offer the same capability for users stored in non-LDAP data sources. For more information, refer to the RecoverableUsername interface in Javadoc.

Tip:

The Javadoc for PingFederate is located in the <pf_install>/pingfederate/sdk/doc directory.

  1. On the System > Data Stores screen, create a new LDAP datastore.
    You can also reuse an existing LDAP datastore connection.
  2. On the System > Password Credential Validators screen, create a new LDAP Username PCV instance.
    You can also reuse an existing LDAP Username PCV instance. If so, skip to step 3b to configure the related advanced fields.
    1. Select a datastore, enter a search base, define a search filter, select the scope of search, and enable or disable case-sensitive matching.
    2. Click Show Advanced Fields to update fields related to self-service user name recovery.
      Configuration items vary depending on your requirements and the directory setup. Refer to the following table for more information.
      Field Description
      Display Name Attribute The LDAP attribute that PingFederate uses to personalize the notification message.

      The default value is displayName.

      Mail Search Filter

      (for username recovery)

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

      mail=${mail}

      Note:

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

      There is no default value.

      Username Attribute

      (for username recovery)

      The LDAP attribute containing the user identifier of the users.
      Note:

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

      There is 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 if the HTML Form Adapter instance is configured to only generate user name recovery notification messages to users who have proven ownership of their email addresses (see this sub step).

      There is no default value.

  3. On the Identity Provider > Adapters screen, create a new HTML Form Adapter instance.
    You can also reuse an existing HTML Form Adapter instance. If so, skip to step 4c to configure your adapter instance to enable the self-service user name recovery capability.
    1. Select the LDAP Username PCV instance defined in the previous step as the credential validator.
    2. Optional: Update any default values or options.
    3. Select the Enable Username Recovery check box.
    4. Select a notification publisher instance from the list.
      If you have not yet configured the desired notification publisher instance, click Manage Notification Publishers.
    5. Click Show Advanced Fields to review or modify default values related to self-service user name recovery.

      For example, select the Require Verified Email check box if you want PingFederate to only send user name recovery email messages to users who have proven ownership of their email addresses.

  4. Optional: Customize and localize the on-screen messages and notification messages.

You have now successfully created a new instance or modified an existing instance of the HTML Form Adapter with the self-service user name recovery capability.

When a user signs on through this adapter instance, the user has the option to recover the user name using the Trouble Signing On link, as illustrated in this screen capture.

A sample sign-on page

Additionally, you can also provide your users the per-adapter Account Recovery endpoint (/ext/pwdreset/Identify), which allows them to recover their user name through this HTML Form Adapter instance without submitting SSO requests.