E-mail Provider for E-mail Token

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

1.10.1. Overview#

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.

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_provider1.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 transferred 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#

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.

1.10.2. Configure E-mail Provider details#

The actual configuration of an E-Mail Provider:


../_images/webui_popup_multiple_email_configuration1.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.

1.10.3. E-mail ProviderConfig#

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

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

This is an example configuration for the SMTPEmailProvider with SSL:

{
 "SMTP_SERVER": "mail.example.com",
 "USE_SSL":"TRUE",
 "SMTP_PORT":"465",
 "SMTP_USER": "smtp-user",
 "SMTP_PASSWORD": "smpt-secret-pwd",
 "EMAIL_FROM": "linotp@example.com",
 "EMAIL_SUBJECT": "Your OTP",
 "TEMPLATE" : "file://enroll2user.eml"
}

The parameters are:

SMTP_SERVER

The domain or IP of the mail server.

"SMTP_SERVER":"mail.example.com"
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_USER":"smtp-user"
SMTP_PASSWORD

The password used to login into the SMTP server.

"SMTP_PASSWORD":"smpt-secret-pwd"
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_FROM":"linotp@example.com"
EMAIL_SUBJECT

The subject of the e-mail. The default value is “Your OTP”.

"EMAIL_SUBJECT":"Your OTP"
START_TLS [functional/optional]

use STARTTLS to secure transmission of e-mails to port 587. Defaults to “False”.

"START_TLS":"True"
CERTFILE [functional / optional]

the certificate of the client to submit the email to the server.

"CERTFILE":"/etc/ssl/certs/smtp_client.crt"
KEYFILE [functional / optional]

client key to submit the email to the server.

"KEYFILE":"/etc/ssl/private/smtp_client.key"
SMTP_PORT [functional/optional]

Set the port of the mail server:

25 - default

587 - STARTTLS

465 - SSL

individual integer

Use SSL port 465 for submitting the email:

"SMTP_PORT":"465"
USE_SSL [functional/optional]

Use port 465 to establish a SSL secured connection. Defaults to “False”.

"USE_SSL":"True"
TEMPLATE [functional/optional]

The template specified here is used to create the mail. “file://” stands for the relative path to the directory ‘/etc/linotp2/custom-templates/mailtemplates/’ The mail template entered there, for example enroll2user.eml, is used when sending the mail. The parameter used there, such as EMAIL_SUBJECT, has a higher priority than the one in the Config section of the provider. Details about the format of a mail template can be found here: E-mail token with notification & templates

"TEMPLATE" : "file://enroll2user.eml"

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.