PingFederate offers self-service password reset (SSPR) for users to recover their account in the event of forgotten password. Integrated into the HTML Form Adapter and Password Credential Validator (PCV) framework, users can now reset their password via one of the following mechanisms:

  • Authentication policy
  • One-time link via email
  • One-time password via email
  • One-time password via text message
  • PingID®

The SSPR capability relies on the HTML Form Adapter and the LDAP Username PCV to query the required attributes for the chosen reset mechanism. 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 SSPR features for users stored in non-LDAP data sources. For more information, refer to the ResettablePasswordCredential interface in Javadoc.

Tip:

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

PingFederate also provides the capability for users to unlock their account without submitting a ticket to the IT department. When enabled with SSPR, if an account is locked, a user can initiate an account unlock request at the Sign On screen or the per-adapter Password Reset endpoint. Through the HTML Form Adapter, PingFederate prompts the user to prove ownership of the account using the password reset flow.

Unlike password reset, when users succeed in proving account ownership, they are allowed to retain their current password or to reset their password as needed. Furthermore, self-service account unlock is only compatible with PingDirectory and Microsoft Active Directory. If the underlying datastore is connected to Oracle Unified Directory or Oracle Directory Server, users can only unlock their account by changing their current password through the password reset flow.

  1. On the System > Data Stores screen, create a new LDAP datastore.
    You can also reuse an existing LDAP datastore connection.
    Important:

    When connecting to an Active Directory (AD) LDAP server, you must secure the datastore connection using LDAPS; AD requires this level of security to allow password changes.

    When connecting to PingDirectory, Oracle Unified Directory, or Oracle Directory Server, configure proxied authorization for the service account on the directory server (see Configuring proxied authorization).

    When connecting to PingDirectory, configure the account usability control ACI for the service account on the directory server if you intend to enable self-service account unlock (see Configuring the account usability control ACI).

  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 SSPR.
      Configuration items vary depending on the desired password reset type 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 Attribute The LDAP attribute containing the email address that PingFederate uses as the destination of the notification message.

      This field is required when the password reset type is Email One-Time Link or Email One-Time Password in any invoking HTML Form Adapter instances.

      The default value is mail.
      SMS Attribute The LDAP attribute containing the phone number, to which PingFederate sends text message notifications to the requesting users.

      This field is required when the password reset type is Text Message in any invoking HTML Form Adapter instances.

      There is no default value.
      PingID Username Attribute The LDAP attribute containing the username to use for PingID based password reset.

      This field is required when the password reset type is PingID in any invoking HTML Form Adapter instances (see step 4e).

      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 SSPR and account unlock capabilities.
    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 Allow Password Changes check box.
    4. Select the Change Password Notification check box if you want PingFederate to generate a notification message for the user who has successfully changed the password through the HTML Form Adapter.
      The destination is the user's email address, specifically the mail attribute value returned by the LDAP Username PCV instance.
    5. Select the desired password reset type.
      Field Description
      Password Reset Type Select one of the following methods for SSPR.
      Authentication Policy
      Based on the policy contract selected from the Password Reset Policy Contract list, PingFederate finds the applicable authentication policy to handle SSPR requests. If the users are able to fulfill the authentication requirements as specified by the policy, PingFederate allows the users to reset their password.
      Email One-Time Link
      Users receive a notification with a URL to reset their password.
      If you have not yet configured the desired notification publisher instance, click Manage Notification Publishers.
      Email One-Time Password
      Users receive a notification with a one-time password (OTP) to reset their password.
      If you have not yet configured the desired notification publisher instance, click Manage Notification Publishers.
      PingID
      Users are prompted to follow the PingID authentication flow to reset their password.
      Ensure the PingID Username Attribute field in the selected LDAP Username PCV instance is configured; otherwise, users will not be able to reset their password.
      You must also download the settings file from the PingOne admin portal and upload the file to the PingID Properties advanced field.
      Important:

      It is recommended that the method used is not already part of a multi-factor authentication policy that includes a password challenge, as that would indirectly reduce that authentication policy to a single factor. For example, if users normally authenticate with a password challenge and then PingID, the SSPR method should not be PingID. Instead, choose the Authentication Policy option, select a policy contract from the Password Reset Policy Contract list, and configure an authentication policy for SSPR.

      Text Message
      Users receive a text message notification with an OTP to reset their password.
      Ensure the SMS Attribute field in the selected LDAP Username PCV instance is configured; otherwise, users will not receive text message notification for password reset.
      If you have not yet configured SMS provider settings in PingFederate, click Manage SMS Provider Settings.
      None
      Users cannot reset password through this HTML Form Adapter instance.

      The default selection is None.

      If a notification publisher instance is configured, PingFederate generates a notification for the user who has successfully reset the password through the HTML Form Adapter. The destination is the user's email address, specifically the value of the attribute defined by the Mail Attribute setting in the LDAP Username PCV instance.
      Password Reset Policy Contract If you use an authentication policy to handle SSPR requests, you must select a policy contract here.

      This policy contract doesn't require any extended attributes because uses this policy only to find the applicable authentication policies for password resets.

      Important:

      You must use a policy contract dedicated only to password reset. You can't use this policy contract for SSO anywhere else. To define a policy contract solely for password reset, click Manage Policy Contracts.

      An authentication policy that uses this contract allows users to reset their password. The policy should use strong authentication methods to securely identify the user. To ensure that the user authenticating in the password reset flow is associated with the target account, you must map the incoming user ID into its authentication sources.
    6. Select the Account Unlock check box if you want to enable self-service account unlock as well.
    7. Select a notification publisher instance from the list.
      If you have not yet configured the desired notification publisher instance, click Manage Notification Publishers.
    8. Click Show Advanced Fields to review or modify the rest of the default values related to SSPR.
      For information regarding the PingID Properties field, refer to the following table.
      Field Description
      PingID Properties For self-service password reset using PingID, follow these steps to upload the PingID settings file to the HTML Form Adapter instance:
      1. Sign on to the PingOne admin portal.
      2. Go to the Setup > PingID > Client Integration screen.
      3. Download the settings file (pingid.properties).
      4. Close the PingOne admin portal.
      5. Come back to the PingFederate administrative console and upload the pingid.properties file to the PingID Properties advanced field on the IdP Adapter screen.
  4. If you have selected Authentication Policy as the password reset type, create a new authentication policy to handle SSPR requests.
    Generally speaking, a password reset policy must authenticate users through means other than prompting for the forgotten passwords. It should also enforce multi-factor authentication for added security. For illustration, consider the following sample use case.
    You have already created an authentication policy to protect SSO requests. This policy uses an HTML Form Adapter instance to validate user credentials and an instance of the PingID Adapter for multi-factor authentication. If users satisfy both authentication requirements, the policy uses a policy contract to relay user attributes to partners. (To learn more about this policy configuration, see Defining authentication policies based on group membership information.)
    Like SSO, you also want to protect SSPR with multi-factor authentication.
    Knowing your company actively manages client certificates on company devices, you have decided to use an instance of the X.509 IdP Adapter (named X.509) as the first-factor authentication source in your password reset policy. You have extended the adapter contract with a CN attribute, through which the adapter exposes the username found in the client certificate. For added security, you intend to leverage PingID as the second-factor authentication source. Per step 4e, you have also created a new policy contract (named SSPR APC) for the sole purpose of SSPR. At this point, you are ready to create your password reset policy.
    1. On the Identity Provider > Policies screen, click Add Policy.
    2. On the Policy screen, enter a name (and optionally a description) for the policy.
    3. Select the X.509 IdP Adapter instance.
    4. Configure each policy path out of the X.509 Adapter instance.
      Fail
      Select Done, which terminates the SSPR request.
      For instance, if a user submits an SSPR request from a personal device, the request will fail because the browser on the personal device is not equipped with the company-managed client certificate issued to that user (that is only available on that user's company device).
      Success
      Select the same PingID Adapter instance that you have created and used in the SSO policy.
    5. Configure incoming user ID for the PingID Adapter instance.
      1. Click Options to open the Incoming User ID dialog.
      2. Select Adapter (X.509) under Source.
      3. Select CN under Attribute.
      4. Click Done to close the Incoming User ID dialog.

        For more information, see Specifying an incoming user ID.

    6. Configure each policy path out of the PingID Adapter instance.
      Fail
      Select Done, which terminates the SSPR request.
      Success
      Select SSPR APC, which is the policy contract created solely for password reset per step 4e.
      Important:

      You must not reuse this policy contract for SSO elsewhere.

    7. Configure contract fulfillment for the selected policy contract.
      Because the sole purpose of the selected policy contract is to route the SSPR requests through this password reset policy, the fulfillment of this contract does not matter. It is not used elsewhere. For instance, you can configure its mapping as follows.
      Contract Attribute Source Value
      subject Text Benign
    8. Click Done and then Save.
    This sample use case demonstrates the capability and flexibility that a password reset policy offers. Depending on actual use cases, you may use a different series of authentication sources to authenticate users in a secure manner. For instance, if your organization manages devices using AirWatch, you may add an instance of the AirWatch Adapter as one of the authentication sources in the password reset policy. Other similar solutions include MobileIron and Microsoft Intune.
  5. 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 SSPR and account unlock capabilities.

When a user signs on through this adapter instance, the user has the option to reset the password or unlock the account 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 reset their password or unlock their account through this HTML Form Adapter instance without submitting SSO requests.