HTML Forms Authenticator

The HTML Forms Authenticator is a Username / Password authenticator that serves HTML pages and connects the data to a Data Source backend using an Account Manager.

It also supports user account registration, password management as well as forgotten user id’s.

Paths

The HTML Forms Authenticator is mounted on the Authentication endpoint with the subpath of it’s 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.

The following tables list the different paths used by the authenticator, as well as the templates rendered by each of them.

Endpoint-kind: auth-authentication

SubPath Method Template Description
index (/) GET authenticate/get.vm The index (/) contains the authentication form
POST authenticate/get.vm The index (/) contains the authentication form
forgot-account-id GET forgot-account-id/get.vm Contains the form where users can enter their email address to recover the corresponding username
POST forgot-account-id/post.vm Information page shown after the user submits the email
forgot-password GET reset-password/get.vm Contains the form where users can enter their email or username to start a password reset
POST reset-password/post.vm Information page shown after the user submits the email/username

Endpoint-kind: auth-registration

SubPath Method Template Description
index (/) GET create-account/get.vm The index (/) contains the registration form
POST create-account/post.vm The index (/) contains the registration form

Endpoint-kind: auth-anonymous

SubPath Method Template Description
set-password GET set-password/landing.vm Users are directed to this endpoint in order to set a new password. The email/reset-password/email.vm email template should include a link to this endpoint by using the _setPasswordUrl template variable. This endpoint is a circuit breaker to prevent non-browser clients from consuming the reset link. The template does a client-side redirect to reset-password and does not contain user-visible content, so it should not be modified.
reset-password GET set-password/get.vm Contains the form where users can actually define the new password. Users should not be directed to this endpoint directly, but rather via a reset password link generated by the server (i.e. via set-password).
POST set-password/post.vm Success page shown after the user submits the password.

Note

In Curity 5.4, the subPath where users actually define their new passwords was changed from set-password to reset-password. If you have a validation script configured to validate new user passwords, ensure that the new path is used.

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 see Validation section.

Email Provider

When an email-provider 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.

Automatic Login

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

  • Account activation.
  • Account activation with mandatory password definition.
  • Account registration, when activation is not required.
  • 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, it can 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.

note:The html-form authenticator will throw a 500 Internal Server Error if it is used directly, when password-only is se to true

Remember Me

The authenticator can be configured with the option show-remember-me-option. This enables a checkbox on the login screen that let’s the user decided 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, then the login form will render this message to the user. A binding message is only accepted from an authenticated (signed or pushed) request.

Configuration

The specific configuration for the HTML Authenticator is the Account Manager, Credential Manager and the Validation Procedure. The HTML Forms Authenticator support 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>