Email¶

The Email Authenticator adds a factor of email to an authentication chain. It can be used standalone, but in most cases it makes more sense to use it as a second or third factor in an authentication flow, or as an additional factor in a registration flow.

The Email Authenticator sends a hyperlink to the user which verifies it is the owner of the email address by clicking the link. Alternatively the Email Authenticator can be configured to send a One Time Password (OTP) code in the 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.

Fig. 60 Email authenticator - Enter username

If the username doesn’t exist or the user doesn’t have a registered email address an error message is displayed. 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.

Caution

This option can only be used when the authenticator is not the first factor, it must either have a pre-requisite authenticator configured, or prompted from an authentication-action. Trying to use the authenticator as a single factor (or first factor) with an intermediate-attribute-name configured will result in an error.

Hyperlink¶

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

Fig. 61 Email Authenticator - Wait

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.

Fig. 62 Email Authenticator - Success

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.

Important

The hyperlink in the email can only be clicked once and is made invalid after use.

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.

Fig. 63 Email Authenticator - OTP Code

Note

For testing purposes, the following system property may be used to tell Curity to use a hardcoded OTP value: se.curity:identity-server:unsafe:hardcoded-otp. This must not be used in production environments.

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. 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.

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:

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

Configuring throttling requires the use of a Bucket Data Sources 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 Database maintenance).

Note

The Email authenticator has supported throttling based on session data for a long time, but that is a much less robust solution than the new (added in version 10.0) throttler which can store data globally. For this reason, the old throttling settings, max-challenges-sent and max-allowed-attempts, have been deprecated in favour of the settings under throttling.

Configuration¶

The general authenticator config is described under Authenticator Base Configuration.

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

Important

The Email Authenticator requires an email provider to be configured on the profile. (Base Configuration of an Authentication Service Profile). To configure email throttling, a Bucket Data Source must be configured.

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>