How to setup MFA with SMS response from the SMS Provider

General behaviour

A SMS is sent with eMail or another mechanism via the VISULOX script service to the SMS provider. The SMS provider delivers the SMS to the recipient. When this is done, the SMS provider can notify the sender about the delivery results. This is mainly done by a HTTP request from the SMS provider.

Within the VISULOX webservice the response from a SMS provider can be inserted into the event database.

VISULOX provides integration examples on request.

In Germany text messages are SMS.

Planning

The SMS is sent via the SMS PIN script. The script has access to server information (VLXPIN_*) (See also: Variables in notifications).

A SMS text should not be longer than 160 characters and should contain at least VLXPIN  and the VLXPIN_SEQUENCE.

Depending on the SMS provider a back channel is possible. Therefore a port is needed, which is reachable by the SMS provider.

This port ends in the SMS response service.

The VISULOX webservice needs to be configured.

SMS delivery script

In this example SMS4.de and Kannel is used.
The Interface to SMS-Expert is no longer supported, because SMS-Expert closed the service at the end of 2016.
Alternate interfaces will be provided on request or OTP can be used as well.

Add the script to the VLX action scripts (example: SMS4.de)

• In SMS4.de a account is needed. SMS4.de will provide a custid (KDNR)
• In SMS4.de a budget is needed.
• in SMS4.de a user (which is not the login user) with a password is needed: USER/PWD

Example script and parameters for SMS via Kannel

visulox config -name sms
    ------------------------------------------------------------------------------
    | changed | key                   | value                                    |
    ------------------------------------------------------------------------------
    |         | regexp.sms            | ^[0-9 +.\(\)-]{6,}$                      |
    |         | smskannel.feedbackurl | http://<server>:<port>/smsKannelfeedback |
    |         | smskannel.gwurl       | <url>                                    |
    |         | smskannel.password    | <password>                               |
    |         | smskannel.postquery   | /cgi-bin/sendsms                         |
    |         | smskannel.sender      | VISULOX RA 2FA PIN                       |
    |         | smskannel.user        | <user>                                   |
    ------------------------------------------------------------------------------

The Webservice is listening initially only on local host.

If SMS Kannel is used with the feedback URL the Webservice has to listen to all interfaces, which can be configured in /opt/visulox/etc/service.conf:

{program webservice.tcl                                                                                          
 enabled false
 requires {webservice}
 args {-interface ""}
}

Another possible solution is via port 443 with a reverse proxy in the Apache:

<Location /smsKannelfeedback>
 ProxyPass        https://localhost:%WEBSERVICESSLPORT%/smsKannelfeedback
 ProxyPassReverse https://localhost:%WEBSERVICESSLPORT%/smsKannelfeedback
</Location>

The text is stored in the VLXPIN_TEXT variable, which is defined in the Login Policy - Notification - Content block.

The format of the message can be enhanced for all messages at once (e.g. to display more than one row): 

#/bin/bash
read -d '' VLXPIN_TEXT << EOF
NICE formatted text
PIN: $VLXPIN_FMT
VALID UNTIL: $VLXPIN_EXPIRATIONTIME
SEQUENCE: $VLXPIN_SEQUENCE
EOF
 
export VLXPIN_TEXT

$VLXUTIL/SMSviaKannel.tcl

The SMS delivery script has to be assigned to an MFA Login Policy.

A timeout parameter can be set for SMSviaKannel.tcl 

Related articles