Autoenrollment of Tokens via SMS or Email

6.1.1. Autoenrollment of Tokens via SMS or Email#

LinOTP can generate a One Time Password (OTP) for a token assigned to a user (stored in e.g. LDAP or AD) and for example send this OTP via email or SMS to the user. This OTP can be used in conjunction with the username and the usual password to improve security of the login.

The autoenrollment feature provides a convenient way to automatically enroll and assign a token to a user the first time an OTP is needed. There is no more need for the administrator or help desk to manually create tokens and allocate them to users.

This guide covers how to setup the autoenrollment feature for LinOTP.

Content of the guide:

  • prerequisites and necessary attributes of the user account

  • creating LinOTP Policies

  • LinOTP Token configuration: SMS and email

  • test scenario

Prerequisites#

You need to prepare a LinOTP instance connected to a userdatabase (e.g. as described in http://www.linotp.org/doc/latest/part-management/quickstart.html#user-id-resolvers). LinOTP must be able to read usernames and verify their passwords. Depending on you method of OTP delivery, the user entry needs to contain sensible content in either the attribute mobile (SMS) or mail (e-mail). These are the default attribute values. However: one can assign any attribute fields of the userstorage to the LinOTP variables in the configuration of the UserIDResolver.

Policies#

To activate and configure autoenrollment, two new LinOTP policies are needed. They can be configured in the management webinterface.

  • The first policy activates the autoenrollment feature, either via SMS or email:

policy for SMS:

../../_images/policy_sms.png

policy for email:

../../_images/policy_email.png

Note: In case both policies are defined please take care they do not overlap in the realm or usernames.

  • The second policy does assign the user password from the UserIdResolver as OTP-PIN so the user can be authenticated by a combination of his username, password and OTP. (which then looks like this: username: username, password: UserPasswordOTP)

policy for password as OTPPIN:

../../_images/policy_otppin.png

Of course it can be restrict who can make use of the autoenrollment feature by activating the policies for only certain users, realms and clients.

Token configuration SMS#

Now you must define, how the SMS is delivered to the user. This is achieved by a LinOTP module, the so called SMSProvider.

the SMS Provider configuration can be found at LinOTP Config -> Provider Config -> SMS Provider Config

../../_images/webui_drop_down_menu_provider.png

The configuration form looks like this:

../../_images/webui_smsprovider_configuration.png

There are five SMS Provider classes available:

  • HttpSMSProvider

LinOTP uses a public SMS gateway as provided e.g. by http://clickatell.com or http://smsout.de. For this flavor please choose smsprovider.HttpSMSProvider.HttpSMSProvider for SMS Provider / class.

  • SmtpSMSProvider

LinOTP sends the messages via a SMTP gateway. The e-mail is addressed to the same receiver and contains certain information, which are parsed by the SMTP gateway. The SMTP gateway will generate and send a SMS with the OTP to the mobilenumber based on the content of the received mail. Please choose smsprovider.SmtpSMSProvider.SmtpSMSProvider for SMS Provider / class.

  • SMPPSMSProvider

Starting with version 2.8.1 LinOTP can send SMS via SMPP protocol as used by many large scale providers for SMS services.

You need to enter smsprovider.SMPPSMSProvider.SMPPSMSProvider for SMS Provider / Class.

Note: The SMPP SMS Provider requires a library not directly available in some distributions - python-smpp. The library can e.g. be installed via pip.

  • DeviceSMSProvider

LinOTP can send the messages directly via a mobile connected to the LinOTP machine. Please choose smsprovider.DeviceSMSProvider.DeviceSMSProvider for SMS Provider / class.

  • RestSMSProvider

LinOTP 3 can submit SMS via the REST API of public available SMS gateways (like Swisscom). You need to enter smsprovider.RestSMSProvider as Class.

SMSProviderConfig#

The configuration of the three SMSProvider differs.

Depending on the type of the SMS Provider, 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 an account name and a password. The other parameters are either functional options like GET (to manipulate the request or configure the expected return values) or mappings for the SMS Provider specific parameters like the destination number. These are needed by LinOTP to know where to put certain necessary information in the request.

SMS_TEXT_KEY [mapping]

denotes, which parameter in the URL will hold the SMS text itself.

Example:

If the Provider requires the content of the SMS to be delivered in a parameter “message”:

"SMS_TEXT_KEY":"message"

The URL will be like this: https://PROVIDER?OTHER_PARAMETERS&message=”This is your OTP: 372873”

SMS_PHONENUMBER_KEY [mapping]

denotes, which parameter in the URL will be used to pass the mobile phone number to which the SMS should be sent.

Example:

If the Provider requires the recipient number in a parameter “phone”:

"SMS_PHONENUMBER_KEY":"phone"

The URL will be like this: https://PROVIDER?OTHER_PARAMETERS&phone=”+49123456789”

HTTP_Method [functional]

denotes, if the API of the SMS Gateway should be used with HTTP GET or HTTP POST request.

USERNAME PASSWORD [functional]

to support HTTP Basic Authentication the parameters USERNAME and PASSWORD can be set.

PROXY [functional]

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 [functional]

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.

Example:

The message was send successfully if the SMS server answers with a string starting with “ok”:

"RETURN_SUCCESS":"ok"
RETURN_SUCCESS_REGEX [functional]

matches the reply of the SMS gateway to indicate successful sending of the SMS with a regular expression.

Example:

The message was send successfully if the SMS server answers with a string containing somewhere “result:0” or “success”:

"RETURN_SUCCESS_REGEX":"(result:0|success)"
RETURN_FAIL [functional]

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.

RETURN_FAIL_REGEX [functional]

matches the reply of the SMS Gateway to indicate the failed sending of the SMS with a regular expression.

Note: To avoid confusion please configure only one of the RETURN_ parameters.

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.

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. subject and body must be shaped in a fitting manner, so the SMTP Gateway can - accordingly to its configuration - construct a SMS to the correct receiver with the desired content.

SMPPSMSProvider#

The configuration for the SmppSMSProvider looks like this:

{ "server":"smpp-server",
  "port":"smmp-port",
  "system_id":"login-name",
  "system_type":"",
  "password":"password",
  "source_addr":"displayed-source-address",
  "source_addr_npi":"0",
  "source_addr_ton":"5",
}
server

IP or hostname of the SMPP Gateway.

port

Destination port at the SMPP Gateway - defaults to 5100.

system_id

Identifies the ESME system requesting to bind s a transmitter with the MC. This field must contain the Short ID (shortcode).

password

Connection password.

system_type [optional]

The service_type parameter can be used to indicate the SMS Application service associated with the message. Specifying the service_type allows the ESME to avail of enhanced messaging services such as “replace by service_type” or to control the teleservice used on the air interface. Can be left empty.

source_addr

Source address. Can be a string instead of a number - this requires to configure source_addr_npi and source_addr_ton to be configured accordingly.

source_addr_npi [optional]

Numbering Plan Indicator for source address. Set this to “0” if your source_address contains anything else than numbers.

source_addr_ton [optional]

Type of number of the ESME source address. Set this to “5” if your source_address contains anything else than numbers.

DeviceSMSProvider#

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

RestSMSProvider#

The configuration for the RestSMSProvider looks like this:

{ "URL":"https://SMSPROVIDERFQDN",
  "PAYLOAD":{
      JSON-REST-DATA
      },
  "HEADERS":{
      REQUIRED-HEADER-DATA
      },
  "SMS_TEXT_KEY":"text",
  "SMS_PHONENUMBER_KEY":"to",
  "USERNAME":"NAME"
  "PASSWORD":"SECRET"
}
URL [required]

holds the link to the API of the SMS Gateway.

PAYLOAD [required]

contains the JSON-Payload as it should be send to the SMS Gateway.

HEADERS [optional]

this holds header information e.g. required for authentication.

SMS_TEXT_KEY [mapping]

defines a placeholder for the message which can be referenced at the required position in the JSON payload.

SMS_PHONENUMBER_KEY [mapping]

defines a placeholder for the phone nubmer which can be referrenced at the required position in the JSON payload.

Authentication [optional]

Sets the type of authentication. Possible values are BASIC and DIGEST. Defaults to BASIC

Proxy [functional/optional]

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.

TIMEOUT [optional]

Configures the connection timeout and the wait time until the request is finished. Defaults to (3,30). Which means LinOTP will try to contact the server for three seconds. If the server answers there will be another 30 seconds for completing the submission of the SMS until the connection is closed by LinOTP.

CLIENT_CERTIFICATE_FILE [optional]

A certificate file can be referenced which is then used to authenticate against the SMS Gateway.

SERVER_CERTIFICATE [optional]

This contains the ROOT-CA to validate the identity of the SMS Gateway. If no server certificate is provided any certificate will be accepted in order to ensure encrypted communication.

This is an example configuration for the Swisscom SMS Gateway: .. code:

{"URL":"https://messagingproxy.swisscom.ch:4300/rest/1.0.0/submit_sm/123456",
 "PAYLOAD": {
 "destination_addr": "<phone>",
 "source_addr":"123456",
 "short_message": "Your OTP is: <message>",
 "source_addr_ton":6,
 "source_addr_npi":0,
 "dest_addr_ton":1,
 "dest_addr_npi":1},
 "SMS_TEXT_KEY":"short_message",
 "SMS_PHONENUMBER_KEY":"destination_addr",
 "PASSWORD": "SECRET",
 "USERNAME":"123456"
}

This is an example configuration for the CLX Communications SMS Gateway: .. code:

{"URL": "https://api.clxcommunications.com/xms/v1/customer27421/batches",
 "PAYLOAD": {
 "to": ["<phone>"],
 "from": "123456789",
 "body":"Your OTP is: <message>"
 },
 "HEADERS": {
 "Authorization": "Bearer e215354ab28041daa3cbf2f11cbd1257",
 "Content-Type": "application/json"
 },
 "SMS_TEXT_KEY": "body",
 "SMS_PHONENUMBER_KEY": "to"
}
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.

Token configuration e-mail#

If you choose to transmit the OTP by mail instead of SMS you have to configure the technical details of the mail delivery. This is done by a special LinOTP module, the so called EmailProvider.

The configuration is done with the webinterface of LinOTP.

LinOTP Config -> Provider Config -> Email Provider Config

../../_images/webui_drop_down_menu_provider.png

Leave the default email Provider as it is: linotp.lib.emailprovider.SMTPEmailProvider.

generic configuration template:

{
"SMTP_SERVER": "mail.example.com",
"SMTP_USER": "smtp-user",
"SMTP_PASSWORD": "smpt-secret-pwd",
"EMAIL_FROM": "linotp@example.com",
"EMAIL_SUBJECT": "Your OTP"
}

The parameters:

SMTP_SERVER

domain or IP of the mail server

SMTP_USER

the username to log into the SMTP server. If you leave this one out (and SMTP_PASSWORD) LinOTP tries to send the mail without authentication. (optional)

SMTP_PASSWORD

the password belonging to SMTP_USER for connecting to the SMTP server (optional)

EMAIL_FROM

the return address - depending on the configuration of the SMTP server this address can be subject to certain restrictions. The used default address is: linotp@example.com (optional)

EMAIL_SUBJECT

the subject of the sent email, by default it is: "Your OTP" (optional)

Note: You must use double quotes, single quotes will result in an error and an unsuccessful email delivery.

Test scenario#

To verify the proper working of the autoenrollment feature, please add a user to the userstorage connected with LinOTP. The user should - depending on the desired method of delivery - have sensible values in either the attribute mail or mobile. Try to login with this user in the web authentication page of LinOTP: http://LINOTPSERVER/auth/index using the regular password of the user. The login should fail, but there will be a message, stating an OTP was sent to the user by SMS or mail. Check the reception of the OTP and login again at http://LINOTPSERVER/auth/index - but this time use the credentials you received:

username: USERNAME

OTP PIN and OTP value: USERPASSWORDOTP

In case the login does not work or the delivery of the OTP fails with an errormessage, please consult the logfile of LinOTP (/var/log/linotp/linotp.log) for further details of the problem.

Finally you should run a test in your infrastructure (e.g. RADIUS) which will later be used by your users for autoenrollment.

Note: If a RADIUS client is used capable of challenge-response mode the challenge is triggert with username and PIN and only the OTP has to be provided in the second authentication step by the user.