Multifactor Authentication Custom Triggers

To create your own custom multifactor authentication trigger, you will need to design a component that is able to resolve events in the CAS authentication chain. The trigger’s (i.e. event resolver’s) job is to examine a set of conditions and requirements and provide an event id to CAS that would indicate the next step in the authentication flow.

A typical custom trigger, as an example, might be:

  • Activate MFA provider identified by mfa-duo if the client browser’s IP address matches the pattern 123.+.

Note that:

  • You are really not doing anything custom per se. All built-in CAS triggers behave in the same exact way when they attempt to resolve the next event.
  • As you will observe below, the event resolution machinery 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 wants to have the next event deal with some form of MFA via a provider, but in theory we could have resolved the next event to be hello-world.

Requirements

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

1
2
3
4
5
<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-core-webflow</artifactId>
    <version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-core-webflow:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-core-webflow"
}
1
2
3
4
5
6
7
8
9
10
dependencies {
    /*
        The following platform references are included automatically and are listed for reference only.

        implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
        implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        
    */
    implementation "org.apereo.cas:cas-server-core-webflow"
}
1
2
3
4
5
<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-core-webflow-mfa-api</artifactId>
    <version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-core-webflow-mfa-api:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-core-webflow-mfa-api"
}
1
2
3
4
5
6
7
8
9
10
dependencies {
    /*
        The following platform references are included automatically and are listed for reference only.

        implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
        implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
        
    */
    implementation "org.apereo.cas:cas-server-core-webflow-mfa-api"
}

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

Design Triggers

The below example demonstrates a reasonable outline of a custom event resolver:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
package org.apereo.cas.custom.mfa;

public class ExampleMultifactorAuthenticationTrigger implements MultifactorAuthenticationTrigger {

    @Autowired
    private CasConfigurationProperties casProperties;

   @Override
   public Optional<MultifactorAuthenticationProvider> isActivated(final Authentication authentication,
                                                                  final RegisteredService registeredService,
                                                                  final HttpServletRequest httpServletRequest,
                                                                  final Service service) {

       return Optional.empty();
   }
}

Register Triggers

The event resolver trigger then needs to be registered as a bean tagged with the @MultifactorAuthenticationWebflowEventResolver annotation. CAS collects every bean carrying this annotation from the application context and adds it to the initial authentication event resolver, so the resolver does not need to locate or register itself with any other component. Resolvers are invoked in the order indicated by their Ordered implementation or @Order annotation, if any.

The below example demonstrates a reasonable outline of a custom event resolver:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
package org.apereo.cas.custom.config;

@AutoConfiguration
@EnableConfigurationProperties(CasConfigurationProperties.class)
public class SomethingConfiguration {
    @Bean
    public MultifactorAuthenticationTrigger exampleMultifactorAuthenticationTrigger() {
        return new ExampleMultifactorAuthenticationTrigger();
    }

    @Bean
    @MultifactorAuthenticationWebflowEventResolver
    public CasWebflowEventResolver exampleMultifactorAuthenticationWebflowEventResolver(
        @Qualifier(CasWebflowEventResolutionConfigurationContext.BEAN_NAME)
        final CasWebflowEventResolutionConfigurationContext casWebflowConfigurationContext,
        @Qualifier("exampleMultifactorAuthenticationTrigger")
        final MultifactorAuthenticationTrigger exampleMultifactorAuthenticationTrigger) {
        return new DefaultMultifactorAuthenticationProviderWebflowEventResolver(
            casWebflowConfigurationContext, exampleMultifactorAuthenticationTrigger);
    }
}
:information_source: Remember

The same annotation must be placed on any bean that replaces one of the built-in trigger event resolvers under the same bean name; a resolver bean without the annotation is not consulted by the initial authentication event resolver.

Do not forget to register the configuration class with CAS. See this guide for better details.