PingFederate Server

HTML Form Adapter advanced fields

When configuring an HTML Form Adapter, you can use the advanced fields at the bottom of the IdP Adapter tab in the Create Adapter Instance window.

Advanced fields for setting password credentials and changes

Property Description

Login Template

(Required)

The HTML core template to prompt the users for their credentials. PingFederate allows each configured adapter instance to use a different login page template.

The default template file is html.form.login.template.html.

Unless otherwise stated, all template files are located in the <pf_install>/pingfederate/server/default/conf/template directory.

Logout Path

Any path in the format indicated. Setting a path invokes adapter logout functionality that is normally invoked during SAML 2.0 single logout (SLO) processing. The resulting logout path is /ext/<Logout Path>. The logout path extends from the base URL. If virtual host names are configured, the logout path is accessible at those locations as well.

Available primarily for use cases where the partner software as a service (SaaS) providers who do not support SAML SLO but want the users' IdP-initiated SSO sessions to end after logging out of the SaaS services. For these use cases, the SaaS providers could redirect the users to the logout URL after the users sign out of their platforms.

If specified, the path must be unique across all HTML Form Adapter instances, including child instances.

This field has no default value.

Logout Redirect

The landing page at the service provider (SP) after successful identity provider (IdP) logout, applicable only when the Logout Path field is configured.

This field has no default value.

Logout Template

The HTML template displayed when a user has successfully logged out in a configuration where the Logout Path field is configured, but the Logout Redirect field is not.

The default template file is idp.logout.success.page.template.html.

Change Password Template

The HTML core template to prompt the users to change their password. PingFederate allows each configured adapter instance to use a different change password template.

The default template file is html.form.change.password.template.html.

Change Password Message Template

The HTML template to be displayed when a user has successfully changed the password through the HTML Form Adapter.

The default template file is html.form.message.template.html.

Password Management System Message Template

The HTML template notifies the users that they are being redirected to a password management system to change their password.

The default template file is html.form.message.template.html.

Password Timeout Update

The time, in minutes, a user has for a password change session on the Change Password and Reset your password pages.

By default, the value is 30 minutes and this feature is enabled. If the field is left blank, this feature is disabled.

  • To use this feature for the self-service password reset (SSPR) flow, you must select a Password Reset Type other than None.

  • To use this feature for the change password with an authentication policy flow, you must select a policy contract for the Change Password Policy Contract and enable Allow Password Changes.

Change Password Email Template

The HTML email template PingFederate uses to generate the email message to notify the user that the password has been changed or reset successfully through the HTML Form Adapter.

The default template file is message-template-end-user-password-change.html, located in the <pf_install>/pingfederate/server/default/conf/template/mail-notifications directory.

Applicable only if an instance of the SMTP Notification Publisher is selected in the Notification Publisher list.

Expiring Password Warning Template

The HTML core template to warn the users about the approaching password expiration day.

The default template file is html.form.password.expiring.notification.template.html.

Threshold for Expiring Password Warning

The threshold, in days, to start warning the user about the approaching the password expiration day.

The default value is 7 days.

Snooze Interval for Expiring Password Warning

The amount of time, in hours, to delay the next warning after the user has chosen to change the password later.

The default value is 24 hours.

Require Re-authentication for Expiring Password Flow

Requires a user to sign on again after changing their password if they initiated the change on the password expiring warning.

By default, this feature is disabled.

Applicable only when the Show Password Expiry Warning is enabled.

Require Re-authentication for Change Password Flow

Requires a user to sign on again with their new password after completing a successful change password flow.

By default, this feature is disabled.

Require Re-authentication for Password Reset Flow

Requires a user to sign on again with their new password after completing a successful password reset or account unlock flow.

By default, this feature is disabled.

Login Challenge Template

The HTML core template to be displayed as the second step during a strong authentication. It is used to prompt the user to answer a challenge question after the first-factor login. The RADIUS Username password credential validator (PCV) is an example of where it could be used.

The default template file is html.form.login.challenge.template.html.

'Remember My Username' Lifetime

The number of days the cookie remains valid. Enter the number of days you want the username remembered in a cookie.

The cookie lifetime is reset upon each successful login in which the Remember my username checkbox on the login form is selected.

The value is ignored 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.

You can enter an integer between 1 and 3650.

The default value is 30 days.

'This is My Device' Lifetime

The number of days that a user’s selection of the This is my device checkbox on the login form is retained.

The lifetime is reset upon each successful login in which the This is my device checkbox on the login form is selected.

You can enter an integer between 1 and 3650.

The default value is 30 days.

Allow Username Edits During Chaining

When users authenticate through a Composite Adapter instance that chains this adapter behind another authentication source with an Input User ID Mapping configuration or initiate an OAuth authorization request with a login_hint parameter, the username in the login form is pre-populated. Users are not allowed to edit their usernames.

Select this checkbox if you want to allow users to edit the pre-populated username in the login form.

Users who authenticate through a Composite Adapter instance without an Input User ID Mapping configuration or this adapter directly always need to enter their usernames.

This checkbox is not selected by default.

Track Authentication Time

When selected, the time of authentication for each user is tracked and can be utilized by applicable use cases. For example, if an OAuth client sends an authorization request with a max_age parameter, the request prompts the user to reauthenticate when the elapsed time between the current time and the time of the previous authentication is greater than the max_age value.

This checkbox is selected by default.

Post-Password Change Re-Authentication Delay

The HTML Form Adapter reauthenticates the user using the new password immediately after a successful password change request. As needed, enter the amount of time, in milliseconds, that the adapter can wait prior to the reauthentication attempt.

The default value is 0, which is the minimum value. The maximum value is 60000, or 1 minute.

Advanced fields for self-service password reset and account unlock

Property Description

Password Reset One-Time Link Email Template

The HTML template to send the user an email with a password reset link when Password Reset Type is Email One-Time Link.

Password Reset One-Time Password Email Template

The HTML template to send the user an email with a one-time password reset code when Password Reset Type is Email One-Time Password.

The default template file is message-template-forgot-password-code.html.

Password Reset Complete Email Template

The HTML template to send the user an email that the password reset is complete.

The default template file is message-template-forgot-password-complete.html.

Password Reset Failed Email Template

The HTML template to send the user an email that the password reset attempt failed.

The default template file is message-template-forgot-password-failed.html.

Password Reset Code Template

The HTML template to prompt the user to enter the one-time passcode (OTP) for password reset.

This template applies when the password reset type is Email One-Time Password or Text Message.

The default template file is forgot-password-resume.html.

Password Reset Template

The HTML template to prompt the user to define a new password.

This template applies for all password reset types other than None.

The default template file is forgot-password-change.html.

Password Reset Error Template

The HTML template to notify the user that the password reset attempt has failed.

This template applies for all password reset types other than None.

The default template file is forgot-password-error.html.

Password Reset Success Template

The HTML template to notify the user that the password reset attempt has succeeded.

This template applies for all password reset types other than None.

The default template file is forgot-password-success.html.

Account Unlock Template

The HTML template to notify the user that the account unlock attempt has succeeded and to prompt the user to retain the current password or reset it.

The default template file is account-unlock.html.

Account Unlock Email Template

The HTML template to send the user an email that the account unlock attempt has succeeded.

The default template file is message-template-account-unlock-complete.html.

OTP Length

The number of characters in the one-time password for password reset.

The default value is 8.

Allowed OTP Character Set

The alphanumeric characters that PingFederate can include in an OTP.

The default value is 23456789BCDFGHJKMNPQRSTVWXZbcdfghjkmnpqrstvwxz.

You must enter a minimum of 10 characters.

Provide unique characters to ensure a secure OTP.

Password Reset Token Validity Time

The validity in minutes for the OTP or the one-time link.

The default value is 10 minutes.

PingID Properties

To configure self-service password reset using PingID, you must obtain the PingID.properties file and upload it to the HTML Form Adapter instance.

  1. Sign on to the PingOne admin portal.

  2. Go to Setup > PingID > Client Integration.

  3. Download the settings file PingID.properties.

  4. Close the PingOne admin portal.

  5. On the Manage IdP Adapters tab in the PingFederate administrative console, click Choose File.

  6. Select the PingID.properties file and click Open.

When configuring an adapter to use a custom template name, make sure the pingfederate/server/default/conf/language-packs/pingfederate-email-messages.properties file and any language specific version, such as pingfederate-email-messages_fr.properties, includes that name so that the email subject found in the properties file is used.

For example, to customize an adapter to use a new password reset complete email template using my-template-forgot-password-complete.html, add the new property with the email’s subject text. The new entry should be my-template-forgot-password-complete.html=Password Reset.

Find the configurable text that applies to a specific template in the pingfederate-email-messages.properties file, and make sure the same key-value pairs are specified for their new template name.

Advanced fields for self-service username recovery

Property Description

Require Verified Email

When selected, PingFederate requires that the user’s email address is verified before sending a password reset, account unlock, or username recovery email.

If users are permitted to manage their accounts, they will be blocked from accessing any connected application until they have verified their email.

Learn more about enabling user account management in Configuring local identity profiles.

By default, the checkbox is cleared.

Username Recovery Template

The HTML template to prompt the user to enter an email address to recover the username associated with the account.

This template applies when username recovery is enabled.

The default template file is username.recovery.template.html.

Username Recovery Info Template

The HTML template to notify the user to retrieve the email message with the recovered username.

This template applies when username recovery is enabled.

The default template file is username.recovery.info.template.html.

Username Recovery Email Template

The HTML email template PingFederate uses to generate the email message that contains the recovered username.

The default template file is message-template-username-recovery.html, located in the <pf_install>/pingfederate/server/default/conf/template/mail-notifications directory.

Applicable only if an instance of the SMTP Notification Publisher is selected in the Notification Publisher list.

Risk options

Property Description

Risk Provider

Select a risk provider. The default selection is Default, which is the risk provider specified as the default on the CAPTCHA and Risk Providers page.

To add a risk provider instance, click Manage CAPTCHA and Risk Providers to open the CAPTCHA and Risk Providers page, then follow the steps in Managing CAPTCHA and risk providers.

Risk for Authentication

Enables risk to protect the authentication process from automated attacks.

Risk for Password Change

Enables risk to protect the password change process from automated attacks.

Risk for Password Reset

Enables risk to protect the account recovery process for password reset and account unlock from automated attacks.

Risk for Username Recovery

Enables risk to protect the username recovery process from automated attacks.

By default, risk checkboxes are cleared.

Other settings

Property Description

Fail Authentication on Account Lockout

This setting determines the adapter’s behavior when PingFederate locks a user’s account due to too many failed login attempts.

  • When selected, the adapter returns an error and policy processing continues on the FAIL branch.

  • When cleared, the adapter displays the login page with an error message stating the account is locked.

The checkbox is cleared by default.

Variables available to HTML Form Adapter templates

The following variables are available to the HTML Form Adapter templates for core templates as well as password reset, change password, and username recovery use cases:

  • $adapterId - The IdP adapter ID used in this transaction

  • $baseUrl - The base URL of the PingFederate instance

  • $client_id - The ID of the OAuth client used in this transaction

  • $connectionName - The name of the SP connection used in this SSO transaction

  • $entityId - The entity ID (connection ID) of the SP connection used in this SSO transaction

  • $spAdapterId - The SP adapter ID used in this transaction

  • $userAttributes - The user-specific data retrieved from the template type used in this transaction. The $userAttributes variable represents the attributes associated with a user’s identity and enables the retrieval of user-specific information across templates

Variables are populated when applicable.

The core templates are:

  • html.form.login.template.html

  • html.form.message.template.html

  • html.form.password.expiring.notification.template.html

  • html.form.login.challenge.template.html