1. Click Identity Provider > Adapters to open the Manage IdP Adapter Instances screen.
  2. On the Manage IdP Adapter Instances screen, click Create New Instance to start the Create Adapter Instance configuration wizard.
  3. On the Type screen, configure the basics of this adapter instance.
    1. Enter the required information and select the adapter type from the list.
    2. Optional: Select a Parent Instance from the list.
      This is useful when you are creating an instance that is similar to an existing instance. The child instance inherits the configuration of its parent. In addition, you have the option to override one or more settings during the rest of the setup. Select the Override ... check box and make the adjustments as needed in one or more subsequent screens.
  4. On the IdP Adapter screen, configure your HTML Form Adapter instance as follows:
    1. If you have not yet defined the desired Password Credential Validator instance, click Manage Password Credential Validators to do so.
    2. Click Add a new row to 'Credential Validators' to select a credential-authentication mechanism instance for this adapter instance.
    3. Select a Password Credential Validator instance from the list and click Update.
      Add as many validators as necessary. Use the up and down arrows to adjust the order in which you want PingFederate to attempt credential authentication. If the first mechanism fails to validate the credentials, PingFederate moves sequentially through the list until credential validation succeeds. If none of the Password Credential Validator instances is able to authenticate the user's credentials, and the challenge retries maximum has been reached, the process fails.
      Note:

      If usernames overlap across multiple Password Credential Validator instances, this failover setup could lockout those accounts in their source locations.

    4. Enter values for the adapter configuration, as described below.
      Field Description
      Challenge Retries

      (Required)

      		 The account lockout threshold for this adapter instance. When the number of login failures reaches this threshold, the user is locked out for a period time.

      The default value is 3.
      Session State Determines whether this HTML Form Adapter instance maintains adapter sessions and shares adapter sessions with other HTML Form Adapter instances.
      Globally
      Adapter sessions from this HTML Form Adapter instance are shared among other HTML Form Adapter instances that use the same Session State field value ('Globally').
      Per Adapter
      HTML Form Adapter maintains adapter sessions on a per-instance basis. Sessions from this HTML Form Adapter instance are not shared with other HTML Form Adapter instances.
      None
      This HTML Form Adapter does not maintain adapter sessions for this HTML Form Adapter instance.
      Note:

      If you intend to enable PingFederate authentication sessions globally or individually for this adapter instance, select None. For more information about PingFederate authentication sessions, see Sessions and Configuring authentication sessions.

      The default selection is None.
      Session Timeout The number of idle minutes before an HTML Form Adapter session times out based on inactivity. If left blank, the lifetime falls back on the Session Max Timeout field value. Ignored if None is selected for the Session State field.

      Applicable only when the Session State field is set to Globally or Per Adapter.

      Tip:

      When you enable PingFederate authentication sessions globally or individually for this adapter instance, you may configure the Idle Timeout setting for the same purpose (see Configuring authentication sessions).

      The default value is 60 (minutes).
      Session Max Timeout The maximum lifetime (in minutes) before an HTML Form Adapter session expires regardless of whether the Session Timeout field value has been reached. Ignored if None is selected for the Session State field.

      Applicable only when the Session State field is set to Globally or Per Adapter.

      Tip:

      When you enable PingFederate authentication sessions globally or individually for this adapter instance, you may configure the Max Timeout setting for the same purpose (see Configuring authentication sessions).

      The default value is 480 (minutes, which translates to 8 hours).

      Note:

      This setting sets a maximum lifetime, subject to inactivity timeout. Consider the following examples:

      A user initiated an SSO request at 9 a.m. and has not made another SSO request since then. At 10 a.m., the HTML Form Adapter session times out based on inactivity (based on the default Session Timeout field value of 60 minutes).

      Another user initiated an SSO request at 9 a.m. and has been making SSO requests every hour at least once. This HTML Form Adapter session does not time out because the user has been actively making SSO requests; however, the HTML Form Adapter session does expire at 5 p.m. (based on the default Session Max Timeout default value of 8 hours).

      If you leave both the Session Max Timeout and Session Timeout fields blank, HTML Form Adapter sessions do not expire (until PingFederate restarts or the HTML Form Adapter sessions are cleaned up by another means).

      If you leave the Session Max Timeout field blank but set a value for the Session Timeout field, HTML Form Adapter sessions do not expire until they time out based on inactivity.

      Tip:

      Session information is stored in the PF cookie. By default, the PF cookie is a session cookie and is typically removed when the user closes the browser.

      You can optionally extend the lifetime of the PF cookie by editing the session-cookie-config.xml file, located in the <pf_install>/pingfederate/server/default/data/config-store directory. For more information, see Extending the lifetime of the PF cookie.

      Alternatively, you can enable PingFederate authentication sessions, store the authentication sessions externally, and leverage them as users request protected resources after restarting their browsers. For more information, see Sessions.

      Allow Password Changes Enables or disables the ability for users to change their network password using this adapter instance as they initiate SSO requests and are prompted to enter their username and password.

      As needed, you may also provide your users the Change Password endpoint shown on the Summary screen. The Change Password endpoint allows users to change their password without submitting SSO requests (see the /ext/pwdchange/Identify section in /ext/pwdchange/Identify).

      Note:

      The LDAP Username Password Credential Validator (PCV) and the PingOne® Directory PCV are currently the only PCVs bundled with PingFederate that support the change password feature.

      Important:

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

      This check box is not selected by default.
      Password Management System The URL for redirecting users to a company-specific password management system to change their password.

      This field has no default value.

      Enable 'Remember My Username' Allows users to store their username as a cookie when authenticating with this adapter. Once stored, the username in the login form is pre-populated for subsequent transactions. Select the check box to enable the cookie functionality.
      Note:

      This option is hidden when users authenticate through a Composite Adapter instance that chains this adapter behind another authentication source with an Input User ID Mapping configuration and the Allow Username Edits check box is not selected.

      This check box is not selected by default.
      Enable 'This is My Device' Allows users to indicate whether their device is shared or private. In this mode, PingFederate authentication sessions (if enabled) are not stored unless the user indicates the device is private. For more information about PingFederate authentication session, see Sessions.

      This check box is not selected by default.

      Note:

      Adapter session tracking (if enabled by setting the Session State field to Globally or Per Adapter) is not affected by this configuration and the user's selection.
      Change Password Notification When selected, a notification is generated 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.
      Note:

      This option requires the selection of the Allow Password Changes check box and a notification publisher instance. If you have not yet configured the desired notification publisher instance, click Manage Notification Publishers.

      In addition, the LDAP Username PCV is the only PCV bundled with PingFederate that supports this notification feature.

      This check box is not selected by default.
      Show Password Expiring Warning When selected, the HTML Form Adapter displays a warning to an authenticated user if the password associated with the account is about to expire soon. The message provides the number of days until the expiry of the current password and the options to change the password immediately or to snooze the message. Both the threshold and the snooze interval are configurable in the Advanced fields section; the default values are 7 days and 24 hours, respectively.
      Note:

      This option requires the selection of the Allow Password Changes check box. (Both check boxes are not selected by default.) In addition, the LDAP Username PCV is currently the only PCV bundled with PingFederate that supports the password expiring warning feature.

      This check box is not selected by default.
      Password Reset Type Select one of the following methods for self-service password reset (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.

      When a selection other than None is made, as users initiate SSO requests and are prompted to enter their username and password, users have the option to reset their password.

      As needed, you may also provide your users the Account Recovery endpoint shown on the Summary screen. The Account Recovery endpoint allows users to change their password without submitting SSO requests (see the /ext/pwdreset/Identify section in IdP endpoints ).

      Note:

      To enable password reset, you must also select the Allow Password Changes check box.

      In addition, the LDAP Username PCV is the only PCV bundled with PingFederate that supports SSPR.

      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.

      Important:

      When connecting to PingDirectory, Oracle Unified Directory, or Oracle Directory Server, configure proxied authorization for the service account on the directory server. For more information, see Configuring proxied authorization.
      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.
      Account Unlock Enables or disables the ability for users to unlock their account using this adapter instance as they initiate SSO requests and are prompted to enter their username and password.

      As needed, you may also provide your users the Account Recovery endpoint shown on the Summary screen. The Account Recovery endpoint allows users to unlock their account without submitting SSO requests (see the /ext/pwdreset/Identify section in IdP endpoints ).

      Note:

      You must also select a Password Reset Type value other than None (and therefore the Allow Password Changes check box as well) because the initiating user must prove ownership of the account through the password reset flow.

      Unlike SSPR, 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 an Oracle Unified Directory or Oracle Directory Server, users can only unlock their account by changing their current password through the password reset flow.

      In addition, the LDAP Username PCV is the only PCV bundled with PingFederate that supports self-service account unlock.

      This check box is not selected by default.
      Local Identity Profile Select a local identity profile to offer users the options to authenticate via third-party identity providers, self-register as part of the sign-on experience, and manage their accounts through a self-service profile management page.

      There is no default selection.
      Notification Publisher If this adapter instance is configured with self-service account management capabilities, select a notification publisher instance from the list.

      Based on selected notification publisher instance configuration, PingFederate generates the required notification messages. If you have not yet configured the desired notification publisher instance, click Manage Notification Publishers.

      Enable Username Recovery Enables or disables the ability for users to recover their username when using this adapter instance as they initiate SSO requests and are prompted to enter their username and password.

      As needed, you may also provide your users the Account Recovery endpoint shown on the Summary screen. The Account Recovery endpoint allows users to recover their username without submitting SSO requests (see the /ext/pwdreset/Identify section in IdP endpoints ).

      Note:

      This capability requires a notification publisher instance. If you have not yet configured the desired notification publisher instance, click Manage Notification Publishers. In addition, the LDAP Username PCV is the only PCV bundled with PingFederate that supports self-service username recovery.

      For each username recovery request, if PingFederate can locate the user record using the email address provided by the user and other requirements are met, PingFederate generates a notification containing the recovered username. The destination is the email address provided by the user.

      This check box is not selected by default.
    5. Optional: Click Show Advanced Fields to review or modify default values.
    6. If you have chosen Text Message as the password reset type, click Manage SMS Provider Settings to configure the SMS provider through which PingFederate can send text message notifications to the users.
  5. On the Extended Contract screen, configure additional attributes for this adapter instance as needed.
    The HTML Form Adapter contract includes two core attributes: username and policy.action. At runtime, PingFederate fulfills the policy.action core attribute as follows:
    Local identity profile Runtime fulfillment
    A selection is made. If the local identity profile is configured with one or more authentication sources, and if the user chooses to register or authenticate via one of them, PingFederate sets the value to that authentication source. This design allows you to create rules in your authentication policies and form different policy paths for each authentication source (see Enabling third-party identity providers).

    Furthermore, regardless of whether the local identity profile is configured with any authentication sources, if the user chooses to register directly by clicking on the Register now link, PingFederate sets the value to identity.registration. This fulfillment allows you to create rules to differentiate authentication requirements from the registration flow (see Creating advanced registration mapping).
    No selection is made. The policy.action attribute is not fulfilled.
  6. On the Adapter Attributes screen, configure the pseudonym and masking options.
    Note:

    The Override Attributes check box in this screen reflects the status of the override option in the Extended Contract screen.

    1. Select the check box under Pseudonym for the user identifier of the adapter and optionally for the other attributes, if available.
      This selection is used if any of your SP partners use pseudonyms for account linking.
      Note:

      A selection is required regardless of whether you use pseudonyms for account linking. This allows account linking to be used later without having to delete and reconfigure the adapter. Ensure that you choose at least one attribute that is unique for each user (for example, email) to prevent the same pseudonym from being assigned to multiple users.

    2. Select the check box under Mask Log Values for any attributes that you want PingFederate to mask their values in its logs at runtime.
    3. Select the Mask all OGNL-expression generated log values check box, if OGNL expressions might be used to map derived values into outgoing assertions and you want those values masked
  7. Optional: On the Adapter Contract Mapping screen, configure the adapter contract for this instance with the following optional workflows:
    • Configure one or more data sources for datastore queries.
    • Fulfill adapter contract with values from the adapter (the default), datastore queries (if configured), context of the request, text, or expressions (if enabled).
    • Set up the Token Authorization framework to validate one or more criteria prior to the issuance of the adapter contract.
  8. On the Summary screen, review your configuration, modify as needed, and click Done to exit the Create Adapter Instance workflow.
  9. On the Manage IdP Adapter Instances screen, click Save to retain the configuration of the adapter instance.
    If you want to exit without saving the configuration, click Cancel.