Multifactor Authentication (MFA)

CAS provides support for a variety of multifactor authentication providers and options, while allowing one to design their own. The secondary authentication factor always kicks in after the primary step and existing authentication sessions will be asked to step-up to the needed multifactor authentication factor, should the request or trigger require it. The satisfied authentication context is communicated back to the application as well to denote a successful multifactor authentication event.

At a minimum, you need answer the following questions:

  • Which provider(s) are we using for multifactor authentication?
  • How and for whom are we triggering multifactor authentication?

Supported Providers

The following multifactor providers are supported by CAS.

Provider Id Instructions
Duo Security mfa-duo See this guide.
Authy Authenticator mfa-authy See this guide.
Acceptto mfa-acceptto See this guide.
YubiKey mfa-yubikey See this guide.
RSA/RADIUS mfa-radius See this guide.
WiKID mfa-radius See this guide.
Google Authenticator mfa-gauth See this guide.
FIDO U2F mfa-u2f See this guide.
FIDO2 WebAuthN mfa-webauthn See this guide.
CAS Simple mfa-simple See this guide.
Swivel Secure mfa-swivel See this guide.
Custom Custom See this guide.


Multifactor authentication can be activated via a number of triggers. To learn more, please see this guide.

Bypass Rules

Each multifactor provider is equipped with options to allow for MFA bypass. To learn more, please see this guide.

Failure Modes

The authentication policy by default supports fail-closed mode, which means that if you attempt to exercise a particular provider available to CAS and the provider cannot be reached, authentication will be stopped and an error will be displayed. You can of course change this behavior so that authentication proceeds without exercising the provider functionality, if that provider cannot respond.

The following failure modes are supported:

Field Description
CLOSED Authentication is blocked if the provider cannot be reached.
OPEN Authentication proceeds yet requested MFA is NOT communicated to the client if provider is unavailable.
PHANTOM Authentication proceeds and requested MFA is communicated to the client if provider is unavailable.
NONE Do not contact the provider at all to check for availability. Assume the provider is available.

Failure Mode Selection

CAS will consult the current configuration in the event that the provider being requested is unreachable to determine how to proceed.
The failure mode can be configured at these locations and CAS will use the first defined failure mode in this order:

  • Registered Service Multifactor Authentication Policy
  • Multifactor Authentication Provider Configuration
  • Global Multifactor Authentication Configuration

If no actionable failure mode is encountered the user will be shown a generic “Authentication Failed” message.

Failure Mode by Registered Service

Set as part of the “multifactorPolicy”. This location will override a failure a mode set at any other location.

  "@class" : "",
  "serviceId" : "^(https|imaps)://.*",
  "id" : 100,
  "multifactorPolicy" : {
    "@class" : "",
    "multifactorAuthenticationProviders" : [ "java.util.LinkedHashSet", [ "mfa-duo" ] ],
    "failureMode" : "CLOSED"

Failure Mode by Multifactor Authentication Provider

Each defined multifactor authentication provider can set its own failure mode policy. Failure modes set at this location will override the global failure mode, but defer to any failure mode set by the registered service.

To see the relevant list of CAS properties, please review this guide.

Global Failure Mode

A default failure mode can be specified globally via CAS properties and will be used in the case where no failure mode is set in either the provider or the registered service.

To see the relevant list of CAS properties, please review this guide.

Multiple Provider Selection

In the event that multiple multifactor authentication providers are determined for a multifactor authentication transaction, by default CAS will attempt to sort the collection of providers based on their rank and will pick one with the highest priority. This use case may arise if multiple triggers are defined where each decides on a different multifactor authentication provider, or the same provider instance is configured multiple times with many instances.

Provider selection may also be carried out using Groovy scripting strategies more dynamically. The following example should serve as an outline of how to select multifactor providers based on a Groovy script:

import java.util.*

class SampleGroovyProviderSelection {
    def String run(final Object... args) {
        def service = args[0]
        def principal = args[1]
        def providersCollection = args[2]
        def logger = args[3]
        return "mfa-duo"

The parameters passed are as follows:

Parameter Description
service The object representing the incoming service provided in the request, if any.
principal The object representing the authenticated principal along with its attributes.
providersCollection The object representing the collection of candidate multifactor providers qualified for the transaction.
logger The object responsible for issuing log messages such as

To see the relevant list of CAS properties, please review this guide.

Ranking Providers

At times, CAS needs to determine the correct provider when step-up authentication is required. Consider for a moment that CAS already has established an SSO session with/without a provider and has reached a level of authentication. Another incoming request attempts to exercise that SSO session with a different and often competing authentication requirement that may differ from the authentication level CAS has already established. Concretely, examples may be:

  • CAS has achieved an SSO session, but a separate request now requires step-up authentication with DuoSecurity.
  • CAS has achieved an SSO session with an authentication level satisfied by DuoSecurity, but a separate request now requires step-up authentication with YubiKey.

In certain scenarios, CAS will attempt to rank authentication levels and compare them with each other. If CAS already has achieved a level that is higher than what the incoming request requires, no step-up authentication will be performed. If the opposite is true, CAS will route the authentication flow to the required authentication level and upon success, will adjust the SSO session with the new higher authentication level now satisfied.

Ranking of authentication methods is done per provider via specific properties for each in CAS settings. Note that the higher the rank value is, the higher on the security scale it remains. A provider that ranks higher with a larger weight value trumps and override others with a lower value.

Provider Selection Menu

If more than one multifactor authentication provider qualifies for the authentication request, CAS may be configured to present all choices to the user, allowing them to select a provider that makes the most sense at a given time. This approach is an alternative strategy to ranking providers.

To see the relevant list of CAS properties, please review this guide.

Trusted Devices/Browsers

CAS is able to natively provide trusted device/browser features as part of any multifactor authentication flow. While certain providers tend to support this feature as well, this behavior is now put into CAS directly providing you with exact control over how devices/browsers are checked, how is that decision remembered for subsequent requests and how you might allow delegated management of those trusted decisions both for admins and end-users.

See this guide for more info.

2FA vs. MFA

Multifactor authentication in CAS mostly presents itself in form of two-factor authentication when deployed. The framework however is designed in such a way to allow additional chaining of other providers into an existing authentication experience. If you have a need to string along multiple factors together one after another, it is likely that you may need to adjust and extend the existing authentication workflows to deliver the use case.


To see the relevant list of CAS properties, please review this guide.