HTML Forms Authenticator

Use Cases#

The HTML Forms authenticator uses a Credential Manager to validate a username and password that the user enters. The HTML Forms authenticator can be run in password-only mode, where the user provides their username to a previous authenticator and then enters only the password in the HTML Forms authenticator.

To implement lifecycle behaviors the authenticator can integrate with other services like an Email Provider and an Account Manager . The configuration of other interfaces influences the behavior of the HTML Form authenticator. You can implement the following main use cases with the HTML Form authenticator.

Getting Started#

The most common way to get started is to create an HTML Forms authenticator in the Admin UI. To do so, navigate to Profiles → Authentication Service → Authenticators and select the + New Authenticator option. Then select the HTML Forms option to see the following user interface.

Paths#

The HTML Forms Authenticator is mounted on the Authentication endpoint with the subpath of its ID. So if an authenticator with the ID html1 is configured and the Authentication endpoint is configured to have the path /authenticate then the paths of the HTML Forms authenticator are found under /authenticate/html1.

Endpoint-kind: auth-authentication#

Endpoint-kind: auth-registration#

Endpoint-kind: auth-anonymous#

Validation Scripts#

The HTML Forms authenticator supports Validation Procedures. These can be configured on all of the listed SubPaths. For more information on Validation Procedures .

Email Provider#

When an HTML Form Authenticator is defined, it will be used for the “forgot password” and “forgot username” features. If it is left unset, then the default email provider configured for the zone will be used.

Email Templates#

The email templates used for verify account, reset password, otp and hyperlink, have been configured to use the account attributes in the email. The attributes which can be used are: id, username, title, name, displayName, nickName, preferredLanguage, locale and timeZone. name is a complex property which itself contains the attributes formatted, givenName, familyName, middleName, honorificPrefix and honorificSuffix.

For example, the email template can use the following syntax to access the user’s given name:

${_account.name.givenName}

Automatic Login#

When enabled, automatic login is available after successfully completing one of the following operations:

1. Account activation.
2. Account activation with mandatory password definition.
3. Account registration, when activation is not required.
4. Setting a new password, after a password recovery flow.

Password Only#

When password-only mode is enabled, the authenticator can only be used as a second factor. It can either be configured to have a previous authenticator , or be triggered by an authentication action (i.e. the multifactor condition action ).

The authenticator will use the subject from the AuthenticatedState and the password provided when submitting the form to authenticate the user. If a different username is posted to the backend, it will be ignored. The username field is disabled by default in the authenticate/get.vm template, it can also be removed with a template override.

Remember Me#

The authenticator can be configured with the option show-remember-me-option . This enables a checkbox on the login screen that lets the user decide if the session should be persisted or not. If the user deselects the checkbox, the SSO cookie will be set as a session cookie only. This means that the cookie will be removed when the browser is closed. This configuration is only available if session cookies are not set as the default on the profile via the sso-cookie-is-session-cookie option.

Binding Message#

When an authentication request includes a binding message, the login form will render this message to the user. A binding message is only accepted from an authenticated (signed or pushed) request.

Throttling#

Account registration can be throttled via the Account Manager .

Password Reset (which normally results in communication being sent to the user) can be throttled by configuring a default Throttler or configuring a throttling service specifically for that purpose in this plugin.

Authentication itself is not normally throttled, but you can easily limit the number of attempts a user can perform within a certain time by using the Credential Policies .

Configuration#

The specific configuration for the HTML Authenticator is the Account Manager , Credential Manager and the Validation Procedures . The HTML Forms Authenticator supports full user management if the selected account manager allows for it.

See the configuration guide for details on the parameters on Authenticators and on the HTML Form Authenticator .

Configuration Example#

<authenticator>
  <id>htmlForms1</id>
  <description>Username authentication</description>
  <template-area>html1</template-area>
  <html-form xmlns="https://curity.se/ns/conf/authenticators/html-form">
    <account-manager>SqlAccountManager</account-manager>
    <credential-manager>DefaultCredentialManager</credential-manager>
    <procedures>
      <validation>
        <request-subpath>forgot-password</request-subpath>
        <endpoint>authenticate1</endpoint>
        <http-method>post</http-method>
        <validation-procedure>forgotPasswordValidator</validation-procedure>
      </validation>
      <validation>
        <request-subpath>index</request-subpath>
        <endpoint>register1</endpoint>
        <http-method>post</http-method>
        <validation-procedure>accountRegistrationValidator</validation-procedure>
      </validation>
    </procedures>
  </html-form>
</authenticator>