Google Authenticator 2FA

This howto will show you how to configure Google Authenticator 2FA on the CAS instance.

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

  1. Prerequisites

  2. CAS configuration

  3. Configuring services

  4. Testing

Prerequisites

There are no special prerequisites other than having iam-app-cas RPM version 0.9 or later. This, automatically, brings in updated definitions for iam-app-directory-server package and service. If you have older versions of these packages installed, update them first and restart both services.

CAS configuration

CAS service container is mostly preconfigured and can be used out of the box. However, you should configure application name and label - those two values are part of the token definition and user application displays them along generated OTP code.

Edit the /data/registry/node-active-config/docker-compose-cas.yml and set CAS_MFA_GAUTH_ISSUER and CAS_MFA_GAUTH_LABEL variables. In the user’s application, the resulting name of the token will be CAS_MFA_GAUTH_ISSUER: CAS_MFA_GAUTH_LABEL: username.

Restart the iam-cas service afterwards.

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-gauth" ] ],
  "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-gauth" ] ],
    "failureMode" : "CLOSED",
  }
}

Testing

To test new configuration, simply try to log into the service you configured 2FA for. If there is no application paired with the account, CAS will present the OTP registration page with QR code and textual representation of the token seed.

  1. Scan the QR code with the Google Authenticator app in your mobile phone.

  2. Wait for the app to generate new code, click on Confirm, enter the code and submit the form.

    • If everything is correct, CAS will remember your app and save the settings.

  3. CAS will show you another page where it asks you to enter the OTP code.

  4. Wait for the app to generate new code, enter it into the form and submit it.

  5. If the code is correct, CAS will proceed with authentication as usual.

Resetting registered OTP

Registered apps are stored inside directory-server LDAP service. Each user account with registered Google Authenticator app has iamUserMfaGauthDevice attribute set.

To reset the app registration, simply delete the attribute from the user’s account and wait about 10-15 minutes for access manager’s cache to expire. Then the user can create new app registration.

IAM appliance’s CAS does not support multiple registered authenticator apps for one user account.