.. _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
~~~~~~~~~~~~~

These values can be configured in the server configuration:

 * EmailProvider
 * EmailProviderConfig
 * EmailChallengeValidityTime
 * EmailBlockingTimeout

.. index::
	EmailProvider, EmailProviderConfig, EmailChallengeValidityTime, EmailBlockingTimeout

EmailProvider
-------------

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

SMTPEmailProvider
~~~~~~~~~~~~~~~~~
.. index::
   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.

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

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.

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

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