Initial user authentication is normally handled outside of the PingFederate server using an application or an IAM system authentication module. Adapters or agents from PingFederate integration kits are typically used to integrate with these local authentication mechanisms.

PingFederate packages an HTML Form Adapter that delegates user authentication to a PCV, such as an LDAP Username PCV. The adapter validates credentials against a user repository through a PCV instance.

To validate against multiple user repositories, you can add multiple PCV instances to an instance of the HTML Form Adapter. In this case, if a PCV instance fails to validate the user credentials, PingFederate uses the next PCV instance.

When PingFederate receives an authentication request and the use case involves an HTML Form Adapter instance, PingFederate invokes the adapter if it does not find a valid authentication session. If the HTML Form Adapter does not find a valid adapter session, it displays a sign-on page and prompts the user for credentials.

If you configure and enable customer IAM, users can optionally register local accounts or sign on using third-party identity providers (IdPs). If a user chooses to sign on using local accounts, the credentials are validated using the designated PCV instance or instances. If validated, PingFederate generates the requested single sign-on (SSO) token or moves the request to the next checkpoint if authentication policies are involved.

In terms of the sign-on experience, the HTML Form Adapter lets you:

  • Use different customizable and localizable template files.
  • Define a logout path or a logout redirect page.
  • Notify users with password expiry information.
  • Let users change or reset their network passwords, or redirect users to a company-hosted password management system.
  • Enable self-service password reset, account unlock, and username recovery.

You can configure all capabilities on a per-adapter instance basis.

PingFederate also tracks sign-on attempts per adapter instance, which adds a layer of protection against brute force and dictionary attacks. When the Challenge Retries threshold is reached, PingFederate locks out the user for a period of time. The default value for the Challenge Retries setting is 3. If a higher value is preferred, consider reviewing the account lockout policy of the user repository first. For example, if the account lockout threshold is set to 5 on the target directory server and the Challenge Retries setting is also set to 5 or higher, the fifth sign-on attempt could lock the user accounts on the directory server. The lockout period is controlled by the Account Locking Service.


The HTML Form Adapter considers a password consisting only of spaces as empty and does not refer to the underlying LDAP for authentication. As a result, while passwords containing only spaces will trigger PingFederate's Account Locking Service, the service will not lock the account at the LDAP level even if the user exceeds the LDAP limit for sign-on attempts. If the LDAP service locks the account due to too many failed sign-on attempts with passwords that contain non-space characters, and a user attempts to log in using a password consisting only of spaces after the Account Locking Service's lockout period has ended, PingFederate will report the situation as an invalid password, rather than a locked account.

This adapter does not provide an authentication context. For SAML connections, PingFederate sets the authentication context as follows:
  • urn:oasis:names:tc:SAML:1.0:am:unspecified for SAML 1.x
  • urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified for SAML 2.0
PingFederate can override the authentication context with either an instance of the Requested AuthN Context Authentication Selector or the SAML_AUTHN_CTX attribute in the SAML attribute contract. The latter takes precedence.

The HTML Form Adapter is authentication API-capable. The PingFederate authentication API is a JSON-based API that enables end-user interactions, such as credential prompts, to be handled by an external web application. This API does so by providing access to the current state of the flow as an end user steps through a PingFederate authentication policy.

For more information, see Authentication applications and the authentication API.