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

10.1. Overview

10.1.1. 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 Challenge Response.

10.1.2. Configuration

These three values can be configured in the server configuration:

• SMSProvider
• SMSProviderConfig
• SMSProviderTimeout

10.2. SMSProvider

An SMSProvider is a LinOTP module, that defines how SMS are sent. At the moment LinOTP comes with two different kinds of SMSProviders.

10.2.1. HttpSMSProvider

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.

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

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

10.3. SMSProviderConfig

Depending on the type of the SMSProvider, this configuration key stores different values.

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

10.3.2. DeviceSMSProvider

The DeviceSMSProvider module uses the tool gnokii [1] 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.

10.3.3. 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” : “<phone>”,
  “body” : “This is your OTP-value: <otp>”
}

The parameters mailuser and mailpassword are optional. The tag <phone> needs to be put where the smtp gateway expects it. This can either be the subject, the body or the mailto. The <phone> tag will be replaced with the mobile phone number of the user. The tag <otp> will be replaced by the generated OTP value. The tag can be places in the subject or in the body.

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

[1]	http://www.gnokii.org/