PingFederate Server

Configuring an HTML Form Adapter instance

In the IdP Adapters page, configure an HTML Form Adapter instance to validate a user authentication session with a password credential validator (PCV) when your initial authentication needs to integrate with an external application or an identity management system (IdM) authentication module.

Steps

  1. Go to Authentication > Integration > IdP Adapters.

  2. On the IdP Adapters page, click Create New Instance to start the Create Adapter Instance configuration.

  3. On the Type tab, configure the basics of this adapter instance:

    1. Enter the Instance Name and Instance ID.

    2. In the Type list, select the adapter type.

    3. (Optional) In the Parent Instance list, select an existing type.

      If you are creating an instance that is similar to an existing instance, consider making it a child instance by specifying a parent. A child instance inherits the configuration of its parent unless overridden. You can specify overrides during the rest of the setup.

  4. On the IdP Adapter tab, configure your HTML Form Adapter instance as follows:

    1. If you have not yet defined the desired PCV instance, click Manage Password Credential Validators.

      A screen capture of the Manage Password Credential Validator button in the Create Adapter Instance page configuration.

    2. Click Add a new row to 'Credential Validators' to select a credential-authentication mechanism instance for this adapter instance.

    3. From the Password Credential Validator Instance list, select a PCV instance. 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 PCV instances can authenticate the user’s credentials, and the challenge retries maximum has been reached, the process fails.

      If usernames overlap across multiple PCV instances, this failover setup could lock out those accounts in their source locations.

    4. Click Add a new row to 'Credential Validators' to select a credential-authentication mechanism instance for this adapter instance.

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

      To enable PingFederate authentication sessions globally or individually for this adapter instance, select None. Learn more about PingFederate authentication sessions in 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.

      When you enable PingFederate authentication sessions globally or individually for this adapter instance, you can configure the Idle Timeout setting for the same purpose. Learn more in 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.

      When you enable PingFederate authentication sessions globally or individually for this adapter instance, you can configure the Max Timeout setting for the same purpose. Learn more in Configuring authentication sessions.

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

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

      • A user initiated an single sign-on (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.

      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. Learn more in Extending the lifetime of the PingFederate 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. Learn more in 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 can also provide your users the Change Password endpoint shown on the Summary page. The Change Password endpoint allows users to change their password without submitting SSO requests. Learn more in the /ext/pwdchange/Identify section.

      The LDAP Username PCV and the PingOne for Enterprise Directory PCV are currently the only PCVs bundled with PingFederate that support the change password feature.

      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 checkbox is cleared 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 checkbox to enable the cookie functionality.

      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 checkbox is not selected.

      This checkbox is cleared by default.

      Enable 'This is My Device'

      Allows users to indicate whether their device is shared or private by selecting the This is my device checkbox on the login form. In this mode, PingFederate authentication sessions, if enabled, are not stored unless the user indicates the device is private. Learn more about PingFederate authentication session in Sessions.

      This checkbox is cleared by default.

      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 Policy Contract

      Select an authentication policy contract to enforce strong authentication requirements, such as multi-factor authentication through PingID, before letting their users change their passwords. This is similar to using a Password Reset Policy Contract.

      The field is empty by default.

      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.

      This option requires the selection of the Allow Password Changes checkbox 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 checkbox is cleared 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 expiration 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.

      This option requires the selection of the Allow Password Changes checkbox. Both checkboxes are cleared by default.

      The LDAP Username PCV is the only PCV bundled with PingFederate that supports the password expiring warning feature.

      To use this option with PingDirectory:

      • Use PingDirectory’s dsconfig utility and a command like the following to enable the ds-pwp-state-json virtual attribute for users with the object class person:

        dsconfig set-virtual-attribute-prop \
   --name "Password Policy State JSON" \
   --set enabled:true \
   --set require-explicit-request-by-name:true \
   --set "filter:(objectClass=person)"

        The ds-pwp-state-json virtual attribute is required for the expiration warning page to function as expected. This attribute was added in PingDirectory 8.2 and cannot be added manually to earlier versions.

      • In PingDirectory, set the return-password-expiration-controls setting in the user’s password policy to always using a command like the following:

        dsconfig set-password-policy-prop \
   --policy-name "Default Password Policy" \
   --set return-password-expiration-controls:always

      • In the LDAP Username PCV, enable the Expect Password Expired Control setting. Learn more in Configuring the LDAP Username Password Credential Validator.

      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 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 passcode (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 because 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 in 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.

      When you make a selection other than None, 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 can also provide your users the Account Recovery endpoint shown on the Summary tab. The Account Recovery endpoint allows users to change their password without submitting SSO requests. Learn more in the /ext/pwdreset/Identify section of IdP endpoints.

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

      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.

      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.

      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.

      Revoke sessions after password change or reset

      Revokes a user’s authentication sessions in other browsers after a password change or reset is completed by this adapter. This option relies on selecting a unique user key attribute for this adapter (learn more in Setting pseudonym and masking options).

      To enable this option, you must also enable the Allow Password Changes option, or set the Password Reset Type option to something other than None.

      This revocation capability is not supported if the IdP session registry is configured with the Directed Clustering - Subclusters state management architecture. Learn more in IdP Session Registry Service and Defining subclusters.

      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 can also provide your users the Account Recovery endpoint shown on the Summary tab. The Account Recovery endpoint allows users to unlock their account without submitting SSO requests. Learn more in the /ext/pwdreset/Identify section of IdP endpoints.

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

      Unlike self-service password reset self-service password reset (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 AD. 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 checkbox is cleared by default.

      Local Identity Profile

      Select a local identity profile to offer users the options to authenticate through 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 can also provide your users the Username Recovery endpoint shown on the Summary tab. The Username Recovery endpoint allows users to recover their username without submitting SSO requests. Learn more the /ext/idrecovery/Recover section of IdP endpoints.

      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 checkbox is cleared by default.

    6. (Optional) Click Show Advanced Fields to review or modify default values.

    7. If you have chosen Text Message as the password reset type, click Manage SMS Provider Settings at the bottom of the page to configure the SMS provider through which PingFederate can send text message notifications to the users.

  5. On the Extended Contract tab, 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 described in the following table.

    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 with 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. Learn more in Enabling third-party identity providers.

    Whether or not 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. Learn more in Creating advanced registration mapping.

    No selection is made.

    The policy.action attribute is not fulfilled.

  6. On the Adapter Attributes tab, do the following:

    1. (Optional) In the Unique User Key Attribute list, select an attribute to uniquely identify users signing on with this adapter.

      The attribute’s value is used to identify user sessions across all adapters. None is selected by default.

      If you choose a custom user key attribute, PingFederate uses the value of the attribute after the Adapter Contract Mapping (if any) has been evaluated. If you choose a custom user key attribute that is based on the username, configure the adapter’s PCV to trim spaces.

      For the HTML Form Adapter, If you enabled the Revoke Sessions after Password Change or Reset option on the IdP Adapter tab, you cannot select None as the unique user key attribute. Doing so results in an error message.

    2. Select the checkbox 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 service provider (SP) partners use pseudonyms for account linking.

      A selection is required whether or not 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, such as a user’s email, to prevent assigning the same pseudonym to multiple users.

    3. Select the checkbox under Mask Log Values for any attributes whose values you want PingFederate to mask in its logs at runtime.

      Masking is not applied to the unique user key attribute in the logs even though the attribute used for the key is marked as Mask Log Values.

    4. If you plan to use OGNL expressions to map derived values into outgoing assertions and want those values masked, select the Mask all OGNL-expression generated log values checkbox.

  7. On the Adapter Contract Mapping tab, 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. (Optional) On the Summary tab, review your configuration and modify as needed. Click Save.

  9. When finished in the IdP Adapters window, click Save to confirm the adapter instance configuration.

    If you want to exit without saving the configuration, click Cancel.