.. _smsprovider: ============================================ SMSProvider for SMS OTP Tokens / Mobile TANs ============================================ Starting with version 2.2 LinOTP also supports sending one time passwords via SMS. In this case an SMS OTP token needs to be created. Internally this token is a HMAC token. The token object gets a mobile phone number and this token is assigned to the user. Overview -------- Triggering SMS ~~~~~~~~~~~~~~ When calling the API ``/validate/smspin`` the user is authenticated by the username and OTP PIN. The sending of an SMS with a OTP value is triggered. This OTP value is valid for a configurable amount of time. A sample webpage can be used at https://your-server-ip/auth/requestsms. Another possibility of triggering SMS is when the user authenticates with username and PIN. When username and PIN are passed to the authentication URL like ``/validate/check`` or ``/validate/simplecheck``, the user is rejected, but, if the PIN is correct, the sending of an SMS is triggered. .. note:: Thus SMS can be easily 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 SMS will be sent to the user. Then the user needs to authenticate with username and PIN+OTP (from the SMS) and the user will be successfully authenticated. Starting with version 2.6 SMS can also be triggered using the new challenge response mechanism described in :ref:`challenge_response`. Configuration ~~~~~~~~~~~~~ These three values can be configured in the server configuration: * SMSProvider * SMSProviderConfig * SMSProviderTimeout .. index:: SMSProvider, SMSProviderTimeout, SMSProviderConfig SMSProvider ----------- An SMSProvider is a LinOTP module, that defines how SMS are sent. At the moment LinOTP comes with two different kinds of SMSProviders. HttpSMSProvider ~~~~~~~~~~~~~~~ .. index:: HttpSMSProvider, Clickatell.com, smsout.de In this case LinOTP uses public available SMS gateways. There are providers like `clickatell.com `_ or `smsout.de `_ that can create an SMS by calling a certain well formed URL. The LinOTP HttpSMSProvider module is designed very flexible, so that every SMS Gateway that either uses HTTP GET or HTTP POST request can be used to send SMS. You need to enter ``smsprovider.HttpSMSProvider.HttpSMSProvider`` as SMSProvider. DeviceSMSProvider ~~~~~~~~~~~~~~~~~ LinOTP also comes with an SMSProvider module to enable the LinOTP server to send SMS itself. This can be achieved by connecting an appropriate phone to the LinOTP machine. The SMS are then send via this phone directly. You need to enter ``smsprovider.DeviceSMSProvider.DeviceSMSProvider`` as SMSProvider. SmtpSMSProvider ~~~~~~~~~~~~~~~ LinOTP can also send SMS via SMTP-Gateways. This means an email is sent to a fixed email address with a certain subject and body. This is interpreted and the gateway sends an SMS to the phone number that is contained either in the subject or the body. You need to enter ``smsprovider.SmtpSMSProvider.SmtpSMSProvider`` as SMSProvider. SMSProviderConfig ----------------- Depending on the type of the SMSProvider, this configuration key stores different values. HttpSMSProvider ~~~~~~~~~~~~~~~ For HttpSMSProvider this is:: {"URL":"http://smsgateway.com/sms_send_api.cgi", "PARAMETER": { "from":"0170111111", "password":"yoursecret", "sender":"name", "account":"company_ltd" }, "SMS_TEXT_KEY":"text", "SMS_PHONENUMBER_KEY":"destination", "HTTP_Method":"GET", "PROXY":"http://username:password@your-proxy:8080", "RETURN_SUCCESS":"ID" } The ``URL`` holds the link to the API of the SMS Gateway. The ``PARAMETER`` can hold any number of fixed parameters, that allow you to use this SMS Gateway to send SMS. Usually this will at least be something like a username or an account and a password. ``SMS_TEXT_KEY`` denotes, which parameter in the URL will hold the SMS text itself. ``SMS_PHONENUMBER_KEY`` denotes, which parameter in the URL will be used to pass the mobile phone number to which the SMS should be sent. ``HTTP_Method`` denotes, if the API of the SMS Gateway should be used with HTTP GET or HTTP POST request. ``USERNAME`` ``PASSWORD`` to support HTTP Basic Authentication the parameters USERNAME and PASSWORD can be set. ``PROXY`` is an optional parameter that needs to be set when the LinOTP server accesses the internet via a proxy. This can be either HTTP or HTTPS and you may specify a username for authenticating to the proxy server. ``RETURN_SUCCESS`` matches the reply of the SMS Gateway to indicate successful sending of the SMS. The first characters of the reply are compared to this definition. ``RETURN_FAIL`` matches the reply of the SMS Gateway to indicate the failed sending of the SMS. The first characters of the reply are compared to this definition. The *RETURN_FAIL* is only evaluated if the *RETURN_SUCCESS* is not defined. This is an example configuration for the clickatell SMS Gateway:: { "URL" : "http://api.clickatell.com/http/sendmsg", "PARAMETER" : { "user":"username", "password":"askme", "api_id":"12980436" }, "SMS_TEXT_KEY":"text", "SMS_PHONENUMBER_KEY":"to", "HTTP_Method":"GET", "PROXY" : "http://user:pass@192.168.100.250:8080", "RETURN_SUCCESS" : "ID" } .. note:: You need to use double quotes and not single quotes! Using single quotes will result in an error and sending SMS will not be possible. DeviceSMSProvider ~~~~~~~~~~~~~~~~~ .. index:: Gnokii The DeviceSMSProvider module uses the tool gnokii [#gnoki]_ to send SMS. The configuration parameter looks like this:: {"CONFIGFILE":"/etc/linotp2/gnokiirc"} where the value of CONFIGFILE reflects the location of the gnokiirc configuration file. A valid configuration file will look like this:: [global] model = AT port = /dev/ttyACM1 connection = serial .. note:: 1. The LinOTP service account needs to have write access on the device defined in the port variable. In this case on /dev/ttyACM1. Usually this can be achieved by adding the LinOTP service account linotp to the group dialout. 2. There were problems reported using gnokii version 0.6.28. It is recommended to use version 0.6.29. SmtpSMSProvider ~~~~~~~~~~~~~~~ The configuration for the SmtpSMSProvider looks like this:: { “mailserver” : “smtp.yourdomain.com”, “mailsender” : “linotp@yourdomain.com”, “mailuser” : “account-to-login-to-smtp-server”, “mailpassword” : “somesecret”, “mailto”: “mailadress@smstp-gateway”, “subject” : “”, “body” : “This is your OTP-value: ” } The parameters mailuser and mailpassword are optional. The tag ```` needs to be put where the smtp gateway expects it. This can either be the subject, the body or the mailto. The ```` tag will be replaced with the mobile phone number of the user. The tag ```` will be replaced by the generated OTP value. The tag can be places in the subject or in the body. SMSProviderTimeout ------------------ This configuration key holds the time that an OTP value that was sent via SMS is valid. This number is interpreted in seconds. The default value is 300 e.g. 5 minutes. That means that after a user requested a SMS OTP he will be able to use this OTP value within the next 5 minutes. If the SMS arrives later or the user will not use this OTP value within 5 minutes, it will not be valid anymore. .. [#gnoki] http://www.gnokii.org/