Apereo CAS - Scripting Multifactor Authentication Triggers


Collaborate
The blog is managed and hosted on GitHub. If you wish to update the contents of this post or if you have found an inaccuracy and wish to make corrections, we recommend that you please submit a pull request to this repository.
Contributed Content
Keith Conger of Colorado College, an active member of the CAS community, was kind enough to contribute this guide.

If you have configured multifactor authentication with CAS with a provider (i.e. Duo Security), you may find yourself in need of conditionally triggering MFA based on a variety of factors rather dynamically. Here is a possible scenario:

  • Allow internal access to a service without forcing MFA via IP range
  • Rejecting external access to a service unless in MFA LDAP group

CAS provides a large number of strategies to trigger multifactor authentication. To deliver the use case, we can take advantage of a Groovy-based trigger to implement said conditions. The script is invoked by CAS globally (regardless of application, user, MFA provider, etc) whose outcome should determine whether an MFA provider can take control of the subsequent step in the authentication flow.

Our starting position is based on the following:

Configuration

With Duo Security configured as our multifactor authentication provider, we can start off with the following settings:

cas.audit.alternateClientAddrHeaderName=X-Forwarded-For
cas.authn.mfa.groovyScript=file:/path/to/GroovyScript.groovy

Here, we are teaching CAS to use the X-Forwarded-For header when fetching client IP addresses, and we are also indicating a reference path to our yet-to-be-written Groovy script.

The script itself would have the following structure:

import java.util.*
import org.apereo.inspektr.common.web.*;

class GroovyMfaScript {

    String privateIPPattern = "(^127\\.0\\.0\\.1)";
    String mfaGroupPattern = "CN=MFA-Enabled";
    String servicePattern = "https://app.example.org";

    def String run(final Object... args) {
        def service = args[0];
        def registeredService = args[1];
        def authentication = args[2];
        def logger = args[3];

        if (service.id.contains(servicePattern)) {
            def clientInfo = ClientInfoHolder.getClientInfo();
            def clientIp = clientInfo.getClientIpAddress();
            logger.info("Client IP [{}]", clientIp);
            if (clientIp.find(privateIPPattern)) {
                logger.info("Internal IP address");

                def memberOf = authentication.principal.attributes['memberOf']
                for (String group : memberOf) {
                    if (group.contains(mfaGroupPattern)) {
                        logger.info("In MFA group");
                        return "mfa-duo";
                    }
                }
                return null;
            }
            return "mfa-duo";
        }
        return null;
    }
}

The above script goes through the following conditions:

  • The requesting application is https://app.example.org.
  • The incoming client IP address matches the pattern (^127\\.0\\.0\\.1).
  • The authenticated user carries a memberOf attribute with a value of CN=MFA-Enabled.

If all of those conditions are true, then MFA is activated…or else ignored. Note that the function of a Groovy trigger is not specific to a multifactor authentication provider. So long as the conditions execute correctly and the provider is configured properly, it can be used to signal any provider back to the authentication flow.

Finale

Thanks to Keith Conger of Colorado College who was kind enough to share the above integration notes.

Misagh Moayyed

Related Posts

Apereo CAS - Microsoft Office 365 SAML2 Integration

Learn how to integrate Microsoft Office 365 with Apereo CAS running as a SAML2 identity provider.

Apereo CAS - HappyFox SAML2 Integration

Learn how to integrate HappyFox with Apereo CAS running as a SAML2 identity provider.

Apereo CAS - Cisco Webex SAML2 Integration

Learn how to integrate Cisco Webex with Apereo CAS running as a SAML2 identity provider.

Apereo CAS - VMware Identity Manager SAML2 Integration

Learn how to integrate VMware Identity Manager with Apereo CAS running as a SAML2 identity provider.

CAS 6.0.0 RC4 Feature Release

...in which I present an overview of CAS 6.0.0 RC4 release.

Apereo CAS 6.0.x - Building CAS Feature Modules

An overview of how various CAS features modules today can be changed and tested from the perspective of a CAS contributor working on the codebase itself to handle a feature request, bug fix, etc.

CAS 6.0.x Deployment - WAR Overlays

Learn how to configure and build your own CAS deployment via the WAR overlay method, get rich quickly, stay healthy indefinitely and respect family and friends in a few very easy steps.

Apereo CAS - Jib at CAS Docker Images

Learn how you may use Jib, an open-source Java containerizer from Google, and its Gradle plugin to build CAS docker images seamlessly without stepping too deep into scripting Dockerfile commands.

Apereo CAS 6 - Administrative Endpoints & Monitoring

Gain insight into your running Apereo CAS 6 deployment in production. Learn how to monitor and manage the server by using HTTP endpoints and gather metrics to diagnose issues and improve performance.

Apereo CAS - SAML2 Metadata with MongoDb

CAS distributed SAML2 metadata management using MongoDB, where you learn how to store metadata documents inside MongoDB for CAS as a SAML2 identity provider and all other registered SAML2 service providers.