Email

that the user enters at the Authenticator screen.

Using as standalone factor (single factor)#

In some cases one wants to use email as a single factor. In such cases the Email Authenticator will start by asking the user for its username.

If the username doesn’t exist or the user doesn’t have a registered email address an error message is displayed, unless prevent-account-enumeration is enabled (see Preventing Account Enumeration). Once the username and email address has been established, the flow continues the same way as the others described below.

Using as second or N-th factor#

The most common case is to use the Email Authenticator as a factor in a multi factor authentication setup. Commonly after a first factor which authenticates the user by a username (which could also be an email address) and a password. The Email Authenticator will then bypass the step of collecting the username again, and will use the username it gets from the SSO session already established by the previous factor.

See Multi-factor configuration for Authentication for how to configure a multi factor authentication chain.

Using an Intermediate Attribute#

You can configure the authenticator to pick up the value for the email from an attribute, by configuring intermediate-attribute-name, instead of using the account manager to fetch it from a database. It is mandatory that the referenced attribute exists in the intermediate attributes, so it has to be set by a previous authenticator or an authentication-action.

Hyperlink#

After the email is sent, the user is directed to a waiting page until the hyperlink is followed.

When the user clicks the hyperlink in the email, the authentication flow resumes automatically. If the hyperlink is followed in a different session (e.g. different user-agent), the user is notified that authentication succeeded and the waiting page on the original user-agent resumes the authentication flow.

If the hyperlink is followed in the same session (e.g. same browser, new tab/window), the authentication flow continues immediately and the waiting page just notifies the user that authentication succeeded (no further action can be done). This behavior can be controlled via the hyperlink-continue-authentication-in-verify-window setting, which defaults to true.

If the link is not clicked within the configured hyperlink-time-to-live number of seconds, the authentication attempt is reset and user may choose to restart the flow to try again.

One Time Password (OTP) Code#

An OTP code will be sent in the email to the user instead of a hyperlink. In this setup the user have to manually enter or copy the code from the email to the authenticator screen to successfully authenticate.

From the Hyperlink or OTP drop-down, select send-otp-as-code. The OTP Time to Live and the OTP Length are both configurable.

Inactive Accounts#

The authenticator by default, does not send hyperlinks to inactive accounts. Instead, an error (error.generic-user-error) is shown to the user, unless prevent-account-enumeration is enabled, in which case an inactive account is indistinguishable from an active one. This behavior is configurable through the allow-inactive-accounts setting. When set to true, the authenticator will send the hyperlink regardless of the account status. Moreover, the setting activate-inactive-accounts, when enabled, allows the authenticator to change the account’s status to active, once the hyperlink is consumed.

Preventing Account Enumeration#

When the authenticator looks up a username, a failed lookup normally produces a distinct error page. Thus allowing account-enumeration: an attacker can submit usernames and read off which ones exist. Enable prevent-account-enumeration to remove that signal. A username that matches no account, matches an account with no email address, or matches an inactive account still follows the same path as a successful one, with the same HTTP status, the same page, the same HAAPI representation and the same response time.

With the option enabled:

• The confirmation page and the HAAPI representation show no email address, whether the account exists or not.
• In OTP mode the user reaches the code form, and any code submitted is rejected, exactly as an incorrect code for a real account is. The max-allowed-attempts ceiling is reached at the same point either way.
• In hyperlink mode the user reaches the waiting page, which polls until the hyperlink time to live expires. This is indistinguishable from a real user who never opens the link.
• Every attempt is counted against the email throttler under the submitted username and the client IP address, whether an account was found, and a sent email is counted under its address. The two outcomes therefore hit the limit after the same number of attempts, and neither can be probed at an unlimited rate.
• Responses are padded to min-response-time (default 1000 milliseconds), so the two outcomes cannot be told apart by timing. This applies to successful attempts too, and is therefore a deliberate cost on every login through the authenticator.

The option is off by default; enabling it requires an account-manager to be configured. It does not apply to backchannel authentication, which reports an unknown user to the client.

As a Second Factor#

When the authenticator runs after a previous factor, a user whose account has no email address, or is inactive, is not told so while the option is enabled. They reach the code form or the waiting page like any other user, and no email arrives. Such a user cannot complete the login through this authenticator, so consider how they are to be enrolled before enabling the option for a second factor.

Email Throttling#

It is a good idea to limit the amount of emails being sent from your Curity instance for multiple reasons. Hence, this authenticator can be configured to throttle sending emails.

This plugin can be configured to use either a Throttler Service (in which case the throttling parameters are configured in the service itself) or an inline throttler configuration consisting of:

• per hour across all clients.
• per hour for each client (identified by the client IP).
• on 5-minute intervals across all clients.

Configuring an inline Throttler, just like a Throttler Service, requires the use of a Bucket data source for storing metadata. It is important to ensure that expired metadata gets cleaned up from the data source periodically, as the volume of data generated can be very large (see JDBCdatabase maintenance).

Configuration#

The general authenticator config is described under Authenticator Base Configuration.

The full configuration settings can be found at Email Authenticator Configuration.

Example:

<authenticator xmlns="https://curity.se/ns/conf/profile/authentication">
    <id>email1</id>
    <previous-authenticator>usernamePassword1</previous-authenticator>
    <email>
        <account-manager-id>myAccountManager</account-manager-id>
        <hyperlink-time-to-live>600</hyperlink-time-to-live>
    </email>
</authenticator>

Example with throttling configured:

<authenticator xmlns="https://curity.se/ns/conf/profile/authentication">
    <id>email2</id>
    <email>
        <account-manager-id>myAccountManager</account-manager-id>
        <hyperlink-time-to-live>600</hyperlink-time-to-live>
        <throttling>
            <bucket>
                <data-source>example-data-source-id</data-source>
            </bucket>
            <max-emails-per-hour>10</max-emails-per-hour>
            <max-emails-in-five-minutes>2</max-emails-in-five-minutes>
            <max-emails-per-client-ip-per-hour>4</max-emails-per-client-ip-per-hour>
        </throttling>
    </email>
</authenticator>

An email authenticator can also be used as a back-channel authenticator.

Example:

<authenticators>
  <backchannel-authenticator>
    <id>email-backchannel-test-authenticator</id>
    <email-backchannel xmlns="https://curity.se/ns/ext-conf/email-backchannel">
      <frontchannel-authenticator>email1</frontchannel-authenticator>
    </email-backchannel>
  </backchannel-authenticator>
</authenticators>