11. E-mail provider for e-mail token

Starting with version 2.6 LinOTP also supports sending one time passwords via e-mail. In this case an e-mail token needs to be created. Internally this token is a HMAC token.

11.1. Overview

11.1.1. Triggering challenge (e-mail)

When calling the API /validate/check with username and only the OTP PIN the server rejects the authentication request. But if the OTP PIN is the correct PIN for the user’s e-mail token, LinOTP sends the challenge (an e-mail containing the OTP) to the user. This challenge is valid for a configurable amount of time.

The user then can authenticate with the OTP PIN and the OTP value from the e-mail.

Note

Thus e-mail tokens can easily be used in conjunction with the RADIUS protocol. The user first needs to authenticate at the RADIUS client with username and PIN. The user will be rejected. After that an e-mail will be sent to the user. Then the user needs to authenticate with username and PIN+OTP (from the e-mail) and the user will be successfully authenticated.

Note

E-mails can also be triggered using the new challenge response mechanism described in Challenge Response.

11.1.2. Configuration

These values can be configured in the server configuration:

  • EmailProvider
  • EmailProviderConfig
  • EmailChallengeValidityTime
  • EmailBlockingTimeout

11.2. EmailProvider

An EmailProvider is a LinOTP module, that defines how e-mails are sent. At the moment LinOTP comes with one EmailProvider.

11.2.1. SMTPEmailProvider

E-mails are sent via SMTP to a server you can configure with EmailProviderConfig.

You need to enter linotp.lib.emailprovider.SMTPEmailProvider as EmailProvider. This is the default value.

11.3. EmailProviderConfig

Depending on the type of the EmailProvider, this configuration key stores different values.

11.3.1. SMTPEmailProvider

For SMTPEmailProvider this is:

{
 "SMTP_SERVER": "mail.example.com",
 "SMTP_USER": "smtp-user",
 "SMTP_PASSWORD": "smpt-secret-pwd",
 "EMAIL_FROM": "linotp@example.com",
 "EMAIL_SUBJECT": "Your OTP"
}
SMTP_SERVER
The domain or IP of the mail server.
SMTP_USER
The username used to login into the SMTP server. If both this and SMTP_PASSWORD are missing the provider will try to send the e-mail without authentication.
SMTP_PASSWORD
The password used to login into the SMTP server.
EMAIL_FROM
The e-mail address that will be used as the sender of the e-mail. Depending on your SMTP server you might be constrained to using your own domain only. The default value is linotp@example.com
EMAIL_SUBJECT
The subject of the e-mail. The default value is “Your OTP”.

Note

You need to use double quotes and not single quotes! Using single quotes will result in an error and sending e-mails will not be possible.

11.4. EmailChallengeValidityTime

How long a challenge will be valid (in seconds). After this time the user will not be able to authenticate even when sending the correct OTP. The default value is 600 seconds (10 minutes).

11.5. EmailBlockingTimeout

Using this value you can prevent several e-mails being sent out almost at the same time because for example your RADIUS server keeps triggering the server to send out challenges every few seconds. During this timeout (in seconds) no new e-mails will be sent and instead the reply will contain the message “e-mail with otp already submitted” and the transaction id of the challenge that is “on its way”. The default value is 120 seconds (2 minutes).