OTP tokens via SMS

This howto will show you how to configure SMS-based OTP authentication.

To use this feature, you need iam-app-cas version 0.9 or later.
Steps to set up SMS OTP

  1. Prerequisites

  2. CAS configuration

  3. Configuring services

  4. Testing

Prerequisites

  • You need to have iam-app-cas RPM version 0.9 or later.

  • You need to have access to a SMS gateway.

  • You need to create a Groovy script to interact with the SMS gateway.

CAS configuration

Create new configuration /data/volumes/cas/cas.services.d/mfa-simple-sms.properties with following contents:

cas.authn.mfa.simple.sms.from=111111111
cas.authn.mfa.simple.sms.text=Your OTP token is %s . Token is valid for 30 seconds.
cas.authn.mfa.simple.sms.attribute-name=mobile
cas.authn.mfa.simple.time-to-kill-in-seconds=60
cas.sms-provider.groovy.location=file:/opt/scripts/sms.groovy

Create Groovy script /data/volumes/cas/scripts/sms.groovy which is called to actually send the message. Following sample script just logs it into the CAS application log and is good only for testing.

import java.util.*

def run(Object[] args) {
    def from = args[0]
    def to = args[1]
    def message = args[2]
    def logger = args[3]

    logger.info("Sending OTP SMS message '${message}' to '${to}' from '${from}'.")
    return true
}

Restart the iam-cas service afterwards.

Parameter

Value

cas.authn.mfa.simple.sms.from

The phone number to send messages from.

cas.authn.mfa.simple.sms.text

The body of the SMS message. The %s is substituted for the OTP token.

cas.authn.mfa.simple.sms.attribute-name

In which attribute to locate user’s phone number. IAM appliance uses mobile as a default.

cas.authn.mfa.simple.time-to-kill-in-seconds

Token validity in seconds. In case of SMS, about 60 seconds is reasonable.

cas.sms-provider.groovy.location

Location of your Groovy script to send SMS messages. Changes to the script are picked up automatically. The appliance directory /data/volumes/cas/scripts/ is mounted into /opt/scripts/ inside the container.

Configuring services

To enable 2FA on particular service, add the following snippet to its application registration.

"multifactorPolicy" : {
  "@class" : "org.apereo.cas.services.DefaultRegisteredServiceMultifactorPolicy",
  "multifactorAuthenticationProviders" : [ "java.util.LinkedHashSet", [ "mfa-simple" ] ],
  "failureMode" : "CLOSED",
}

The final result may look like this (example for idm-200.json):

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "https://iam.appliance.tld/idm.+",
  "name" : "CzechIdM",
  "id" : 200,
  "evaluationOrder" : 1,
  "multifactorPolicy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceMultifactorPolicy",
    "multifactorAuthenticationProviders" : [ "java.util.LinkedHashSet", [ "mfa-simple" ] ],
    "failureMode" : "CLOSED",
  }
}

Testing

To test new configuration, simply try to log into the service you configured 2FA for. CAS will send OTP code CASMFA-XXXXXX to the user, which will be logged in the application log. When the user enters the code, CAS validates it and performs the authentication.

If the user account has no mobile attribute set, the 2FA will fail.