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.

Base Configuration¶

The Authenticator base configuration is found in the general section Authenticator Base Configuration.

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. 56 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. 57 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. 58 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.

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.

Configuration¶

The general authenticator config is described under Authenticator Base Configuration. This section describes the additional parameters that are available for the Email Authenticator.

Important

The Email Authenticator is located in the configuration at /profiles/profile{id type}/settings/authentication-service/authenticators/authenticator{id}/email

The available parameters for the Email Authenticator are

class email

account-manager-id(ref, mandatory)

A reference to an account manager in the profile. This account manager must have a data-store configured for Registration to be possible. Otherwise the authenticator will operate in authentication mode only.

hyperlink-time-to-live(integer, default 120)

The time (in seconds) the hyperlink sent out will be valid for authentication.

hyperlink-continue-authentication-in-verify-window(boolean, default true)

Whether authentication should continue in the browser window/tab where the hyperlink is verified. This is only possible when the hyperlink is verified in the same session as it was requested.

max-challenges-sent(integer between 0 and 100, default 3): The maximum number of Email-challenges that is allowed to be sent during one session. When this value is set to 0, there is no maximum attempts enforced.

max-allowed-attempts(integer between 0 and 100, default 3): This setting restricts how many attempts a user can do to verify a link within a session. If the limit is reached, an error verify.error.too-many-attempts will be shown. Setting this to 0, allows for unlimited attempts.

allow-inactive-accounts(boolean, default false): If set to true, the authenticator will not check if the account is active before sending the hyperlink.

activate-inactive-accounts(boolean, default false): If set to true, the authenticator will change the account status to active once the hyperlink sent was consumed by the user.

Important

The Email Authenticator requires an email provider to be configured on the profile. (Base Configuration of an Authentication Service Profile)

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>

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>