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