PingFederate Server

Configuring self-service account recovery

PingFederate offers self-service password reset for users to recover their accounts if they forgot their passwords.

About this task

Integrated into the HTML Form Adapter and password credential validator (PCV) framework, users reset their passwords through one of the following mechanisms:

  • Authentication policy

  • One-time link through email

  • One-time password through email

  • One-time password through text message

  • PingID - The PingID account recovery option requires users to already have a PingID account.

The self-service password reset capability relies on the HTML Form Adapter and the Lightweight Directory Access Protocol (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 can also be developed to offer the self-service password reset features for users stored in non-LDAP data sources. Learn more about the ResettablePasswordCredential interface in its Javadoc.

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

Steps

  1. Create a new LDAP datastore. You can find instructions in Configuring an LDAP connection.

    You can also reuse an existing LDAP datastore connection.

    • 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. Learn more in Proxied authorization.

    • When connecting to PingDirectory, you can configure the pwdAccountLockedTime attribute type for the service account on the directory server to allow PingFederate account recovery to unlock locked PingDirectory accounts. Learn more in Allowing PingFederate to unlock PingDirectory accounts.

    • For self-service account recovery to work correctly with PingDirectory, you must grant the service account the password-reset privilege. In PingDirectory use the ldapmodify command to apply the following change:

      dn: uid=pfadmin,ou=People,dc=example,dc=com
changetype: modify
add: ds-privilege-name
ds-privilege-name: password-reset

  2. Create an LDAP username password credential validator. You can find instructions in Configuring the LDAP Username Password Credential Validator.

    The advanced fields on the Instance Configuration tab allow you to configure self-service password reset, account unlock, and user name recovery through the HTML Form Adapter

  3. Create a new HTML Form Adapter instance. Configuring an HTML Form Adapter instance and HTML Form Adapter advanced fields have complete field descriptions.

    1. Go to Authentication > Integration > IdP Adapters.

    2. In the IdP Adapters page, click Create New Instance.

    3. On the Type tab, enter an instance name and ID.

    4. From the Type list, select HTML Form IdP Adapter, and click Next.

    5. On the IdP Adapter tab, click Add a new row to 'Credential Validators' and select the LDAP Username PCF instance defined in step 2.

    6. Select the Allow Password Changes checkbox.

    7. Select the Change Password Notification checkbox if you want PingFederate to generate a notification message for a user who has successfully changed their password through the HTML Form Adapter.

      The message is sent to the user’s email address, specifically the mail attribute value returned by the LDAP Username PCV instance.

    8. Select a Password Reset Type. See the following table for more information.

      Field Description

      Password Reset Type

      Select one of the following methods for self-service password reset.

      Authentication Policy

      Based on the policy contract selected from the Password Reset Policy Contract list, PingFederate finds the applicable authentication policy to handle self-service password reset 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.

      Do not use a method that is already part of a multi-factor authentication (MFA) 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 self-service password reset 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 self-service password reset.
      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 PingFederate uses this policy only to find the applicable authentication policies for password resets.

      You must use a policy contract dedicated only to password reset. You can’t use this policy contract for single sign-on (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. Ensure the policy uses strong authentication methods to securely identify the user who initiated the password reset operation. Map the incoming user ID for adapters in the policy to Requested User and confirm that adapters will only return success when this user is the one authenticating.

      Developing IdP adapters has guidelines on designing adapters for use in password reset or password change authentication policies.

    9. Select the Account Unlock checkbox if you want to enable self-service account unlock as well.

    10. Select a notification publisher instance from the list.

      If you have not yet configured the desired notification publisher instance, click Manage Notification Publishers.

    11. Click Show Advanced Fields to review or modify the rest of the default values related to self-service password reset. HTML Form Adapter advanced fields has descriptions of all advanced fields.

  4. If you selected Authentication Policy as the password reset type, create a new authentication policy to handle self-service password reset requests.

    Generally a password reset policy must authenticate users through means other than prompting for the forgotten passwords. It should also enforce MFA for added security. 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 MFA. If users satisfy both authentication requirements, the policy uses a policy contract to relay user attributes to partners. Learn more about this policy configuration in Defining authentication policies based on group membership information.

    Like SSO, you also want to protect self-service password reset with MFA.

    Knowing your company actively manages client certificates on company devices, you have decided to use an instance of the X.509 identity provider (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 3e, 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 Authentication > Policies > Policies, click Add Policy.

    2. On the Policy window, 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 self-service password reset request. For instance, if a user submits an self-service password reset 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 the 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.

        Learn more in Specifying incoming user IDs.

    6. Configure each policy path out of the PingID Adapter instance.

      Fail

      Select Done, which terminates the self-service password reset request.

      Success

      Select SSPR APC, which is the policy contract created solely for password reset per step 3e.

      You must not reuse this policy contract for SSO elsewhere.

    7. Configure the 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 Save.

      This sample use case demonstrates the capability and flexibility that a password reset policy offers. Depending on actual use cases, you can use a different series of authentication sources to authenticate users in a secure manner. For example, if your organization manages devices using AirWatch, you can 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.

Result

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

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.