.. _emailprovider: ============================================ 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. 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 :ref:`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. | .. figure:: images/webui_drop_down_menu_provider.png :width: 60% 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". .. figure:: images/webui_mail_provider_imported_default.png :width: 70% 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. .. figure:: images/webui_popup_multiple_email_provider_populated.png :width: 80% 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=** * User: This is a comma separated list of usernames or resolver names. Please see :ref:`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. .. _e-mail-provider-details: Configure E-mail Provider details ---------------------------------- The actual configuration of an E-Mail Provider: | .. figure:: images/webui_popup_multiple_email_configuration1.png :width: 70% | 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 definition of how long the E-Mail provider tries to connect the defined peer to submit the E-Mail. The timeout value contains one or two values (in seconds) of the format '120.0;7.5'. The first value is the connection timeout, while the second value (optional, available in LinOTP >=2.8.1.2) is the time to wait for an answer from the peer. The default connection timeout value is 120 e.g. 2 minutes. The E-Mail provider timeout is independent of the E-Mail OTP expiration time, which could be specified in the menu 'Token Configuration' under the 'E-Mail Token' settings. E-mail ProviderConfig ----------------------- Depending on the type of the E-mail Provider, this configuration key stores different values. SMTPEmailProvider ~~~~~~~~~~~~~~~~~~ .. index:: 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. .. figure:: images/webui_popup_multiple_email_configuration1.png :width: 70% | **This is an example configuration for the SMTPEmailProvider with SSL**:: { "SMTP_SERVER": "mail.example.com", "USE_SSL":"TRUE", "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. .. code:: "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. .. code:: "SMTP_USER":"smtp-user" ``SMTP_PASSWORD`` The password used to login into the SMTP server. .. code:: "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 .. code:: "EMAIL_FROM":"linotp@example.com" ``EMAIL_SUBJECT`` The subject of the e-mail. The default value is "Your OTP". .. code:: "EMAIL_SUBJECT":"Your OTP" ``START_TLS`` [functional/optional] use STARTTLS to secure transmission of e-mails to port 587. Defaults to "False". .. code:: "START_TLS":"True" ``CERTFILE`` [functional / optional] the certificate of the client to submit the email to the server. .. code:: "CERTFILE":"/etc/ssl/certs/smtp_client.crt" ``KEYFILE`` [functional / optional] client key to submit the email to the server. .. code:: "KEYFILE":"/etc/ssl/private/smtp_client.key" ``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: .. code:: "PORT":"465" ``USE_SSL`` [functional/optional] Use port 465 to establish a SSL secured connection. Defaults to "False". .. code:: "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: :ref:`mail_templates` .. code:: "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 :ref:`policy_auth_email_subject`.