OTP tokens via e-mail

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

To use this feature, you need iam-app-cas version 0.9 or later.

Steps to set up E-mail OTP

Prerequisites
CAS configuration
Configuring services
Testing

Prerequisites

You need to have iam-app-cas RPM version 0.9 or later.
You need to have a mail proxy in your infrastructure.

CAS configuration

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

spring.mail.host=mailproxy.yourdomain.tld
spring.mail.port=25
# if the proxy is down during CAS startup, the startup will not fail
spring.mail.testConnection=false

cas.authn.mfa.simple.mail.from=cas@yourdomain.tld
cas.authn.mfa.simple.mail.subject=CAS MFA Token
cas.authn.mfa.simple.mail.text=Hello! Your OTP token is %s . Token is valid for 30 seconds.
cas.authn.mfa.simple.mail.attribute-name=mail
cas.authn.mfa.simple.time-to-kill-in-seconds=300

Restart the iam-cas service afterwards.

Parameter

Value

spring.mail.host

Hostname or IP address of your e-mail proxy.

spring.mail.port

Network port of your mail proxy.

cas.authn.mfa.simple.mail.from

The From: part of the e-mail message.

cas.authn.mfa.simple.mail.subject

The Subject: part of the e-mail message.

cas.authn.mfa.simple.mail.text

The body of the e-mail message. The %s is substituted for the OTP token.

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

In which attribute to locate user’s e-mail address. IAM appliance uses mail as a default.

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

Token validity in seconds. In case of e-mail, at least five to ten minutes is recommended.

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 the e-mail with OTP code CASMFA-XXXXXX to the user. When the user enters the code, CAS validates it and performs the authentication.

If the user account has no mail attribute set, the 2FA will be skipped for this user.