Activating MFA in CAS 5


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.

Perhaps one of the more attractive features of CAS 5 is the ability to support multifactor authentication via a number of providers/vendors that can be triggered in many ways. While support for triggers may seem extensive, there is always that edge use case that would have you trigger MFA based on a special set of requirements.

Here is what you can do.

Audience

This post is intended for java developers with a basic-to-medium familiarity with Spring, Spring Boot and Spring Webflow. This is NOT a tutorial to be used verbatim via copy/paste. It is instead a recipe for developers to extend CAS based on specialized requirements.

Stop Coding

Hearken to the reed flute, how it complains, lamenting its banishment from its home: “Ever since they tore me from my osier bed, my plaintive notes have moved men and women to tears. I burst my breast, striving to give vent to sighs, and to express the pangs of my yearning for my home. He who abides far away from his home is ever longing for the day he shall return.

[The Reed Flute’s Song, Rumi, 1207-1273]

Before diving into code, I MUST emphasize that developing custom extensions/addons, while certainly keeewl and exciting, would eventually lead to long-term maintenance/upgrade burdens. Consider direct contributions to the project if/when feasible and solve the problem where it needs solving.

If you are going to write code, you might as well write it where it belongs.

Requirements

You will need to have compile-time access to the following modules:

  • org.apereo.cas:cas-server-core-webflow
  • org.apereo.cas:cas-server-core-web

These are modules that ship with CAS by default and thou shall mark them with a compile or provided scope in your build configuration.

Create MFA Triggers

You should create an event resolver that houses and implements your special requirements for MFA. A typical example might be: Activate MFA provider mfa-duo if the request client IP address matches the pattern 123.+

package org.apereo.cas.custom.mfa;

public class CustomWebflowEventResolver extends AbstractCasWebflowEventResolver {

    @Autowired
    private CasConfigurationProperties casProperties;

    @Override
    protected Set<Event> resolveInternal(final RequestContext context) {
        final RegisteredService service = WebUtils.getRegisteredService(context);
        final Authentication authentication = WebUtils.getAuthentication(context);
        final HttpServletRequest request = WebUtils.getHttpServletRequest(context);

        final Map<String, MultifactorAuthenticationProvider> providerMap =
            WebUtils.getAllMultifactorAuthenticationProviders(this.applicationContext);

        // Somehow, select a provider based on the above map...    
        final MultifactorAuthenticationProvider provider = ...

        if (areWeDoingMfa()) {
            final Event event = validateEventIdForMatchingTransitionInContext(provider.getId(), context,
                        buildEventAttributeMap(authentication.getPrincipal(), service, provider)));
            return ImmutableSet.of(event);
        }
        logger.warn("Not doing MFA, sorry.");
        return null;
    }
}

Note that you have full access to the resolved CAS authentication, the principal associated with it, the service requesting authentication as well as the original web request. You also have access to the full body of CAS configuration settings, should you need to externalize values.

Register MFA Triggers

Your trigger then needs to be registered. We do this via CAS’ native auto-configuration strategy, which scans the application context for relevant annotations inside org.apereo.cas sub-packages. If you change package names, you MUST account for the custom context scan too.

package org.apereo.cas.custom.config;

@Configuration("SomethingConfiguration")
public class SomethingConfiguration {

    @Autowired
    @Qualifier("initialAuthenticationAttemptWebflowEventResolver")
    private CasDelegatingWebflowEventResolver initialEventResolver;

    @RefreshScope
    @Bean
    public CasWebflowEventResolver customWebflowEventResolver() {
        return new CustomWebflowEventResolver();
    }

    @PostConstruct
    public void initialize() {
        initialEventResolver.addDelegate(customWebflowEventResolver());
    }
}

We simply register our trigger as a Spring @Bean and add it to the chain of event resolvers that kick into action as part of CAS authentication machinery.

So…

Note that:

  • You are really not doing anything custom. All CAS triggers behave in the same exact way when they attempt to resolve the next event.
  • The API is completely oblivious to multifactor authentication; all it cares about is finding the next event in the chain in a very generic way. Our custom implementation of course makes the next event be concerned about MFA but in theory we could have resolved the next event to be hello-world and CAS would not have cared.

Happy Coding!

Misagh Moayyed

Related Posts

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.

Apereo CAS - Slurp Configuration with Groovy

Learn how CAS configuration may be consumed via Groovy to simplify and consolidate settings for multiple deployment environments and profiles.

Apereo CAS - Configuration Management with MongoDb

CAS distributed configuration management using MongoDb, where you learn how to store and secure CAS configuration settings and properties inside MongoDb.

Apereo CAS - Integration with HashiCorp Vault

CAS distributed configuration management using HashCorp Vault, where you learn how to store and secure CAS configuration settings and properties inside Vault.

CAS 6.0.0 RC3 Feature Release

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