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

10.1. Overview

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

10.1.2. Configuration

Starting with LinOTP 2.9 more than one E-mail Provider can be configured. The configuration moved from “LinOTP Config” –> “Token Config” –> “E-mail OTP Token” to an extra entry “LinOTP Config” –> “Provider Config” –> “Email Provider Config” where the providers can be created, edited and deleted.


../_images/webui_drop_down_menu_provider.png

New configuration menu for multiple SMS/Email Providers


Note

If the system was updated to LinOTP version 2.9+ an E-mail Provider previously configured is automatically transfered to the new configuration environment and named “imported_default”.

../_images/webui_mail_provider_imported_default.png

Imported E-Mail Provider from previous configuration

Set up as many E-mail Provider as required. Which one will be used to deliver the e-mail can be configured by policies. If no policy exists or no existing policy applies the E-mail Provider marked as “(Default)” will be used.

../_images/webui_popup_multiple_email_provider_populated.png

Multiple E-Mail Provider configured

10.1.2.1. Policy to choose E-Mail Provider

  • Policy name: this is a unique name of the policy.
  • Scope: You need to set this to authentication.
  • Action: email_provider=<NAME_A_CONFIGURED_PROVIDERS>
  • User: This is a comma separated list of usernames or resolver names. Please see Users in policies.
  • Realm: Enter the name of the realm.
  • Client: This is a list of IP addresses or subnets this policy is valid for.

10.2. Configure E-mail Provider

The actual configuration of an E-Mail Provider:


../_images/webui_popup_multiple_email_configuration.png

An E-mail Provider is a LinOTP module, that defines how e-mails are sent. At the moment LinOTP comes with one E-mail Provider: SMTPEmailProvider.

These four values can be configured in the server configuration:

Name
Name of the SMS Provider as to be used in the policies.
Class

The E-mail Provider module to be used for sending e-mail. At the moment LinOTP comes with one E-Mail Provider class:

  • SMTPEmailProvider

The configuration is described below.

Config
The configuration parameter for the E-Mail Provider class.
Timeout
This configuration key holds the time that an OTP value that was sent via e-mail is valid. The number is interpreted in seconds. The default value is 120 e.g. 2 minutes. That means that after a user requested OTP by e-mail the OTP will be valid within the next 2 minutes. If the e-mail arrives later or the user will not use this OTP value within 2 minutes, it will not be valid anymore.

10.3. E-mail ProviderConfig

Depending on the type of the E-mail Provider, this configuration key stores different values.

10.3.1. SMTPEmailProvider

E-mails are sent via SMTP to a server.

You need to enter linotp.lib.emailprovider.SMTPEmailProvider as Provider (LinOTP prior 2.9) or Class. This is the default value.

../_images/webui_popup_multiple_email_configuration.png

This is an example configuration for the SMTPEmailProvider:

{
 "SMTP_SERVER": "mail.example.com",
 "SMTP_USER": "smtp-user",
 "SMTP_PASSWORD": "smpt-secret-pwd",
 "EMAIL_FROM": "linotp@example.com",
 "EMAIL_SUBJECT": "Your OTP"
}

The parameters are:

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.

Note

The e-mail subject can be customized via policy, see Email Subject.