FIDO2 WebAuthn Multifactor Authentication

WebAuthn is an API that makes it very easy for a relying party, such as a web service, to integrate strong authentication into applications using support built in to all leading browsers and platforms. This means that web services can now easily offer their users strong authentication with a choice of authenticators such as security keys or built-in platform authenticators such as biometric readers.

Support is enabled by including the following module in the WAR overlay:

<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-support-webauthn</artifactId>
    <version>${cas.version}</version>
</dependency>

implementation "org.apereo.cas:cas-server-support-webauthn:${project.'cas.version'}"

dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-support-webauthn"
}

dependencies {
    /*
    The following platform references should be included automatically and are listed here 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-support-webauthn"
}

The following settings and properties are available from the CAS configuration catalog:

_{The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.}

cas.authn.mfa.web-authn.core.trusted-device-metadata.location=

The location of the resource. Resources can be URLS, or files found either on the classpath or outside somewhere in the file system.

In the event the configured resource is a Groovy script, specially if the script set to reload on changes, you may need to adjust the total number of inotify instances. On Linux, you may need to add the following line to /etc/sysctl.conf: fs.inotify.max_user_instances = 256.

You can check the current value via cat /proc/sys/fs/inotify/max_user_instances.

org.apereo.cas.configuration.model.SpringResourceProperties.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.authn.mfa.web-authn.core.trusted-device-metadata.location=...

This is the most common form of property configuration that is recognized by CAS, regardless of the actual property source, which might in fact be managed separately outside the CAS environment, by another system or cloud framework.

CAS properties can be specified using the YAML syntax:

cas: 
  authn: 
    mfa: 
      web-authn: 
        core: 
          trusted-device-metadata: 
            location: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.authn.mfa.web-authn.core.trusted-device-metadata.location="..." -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory. Note the placement of the system property which must be specified before the CAS web application is launched.

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_AUTHN_MFA_WEB_AUTHN_CORE_TRUSTED_DEVICE_METADATA_LOCATION="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.authn.mfa.web-authn.core.trusted-device-metadata.location="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

cas.authn.mfa.web-authn.core.application-id=

The extension input to set for the appid extension when initiating authentication operations. If this member is set, starting an assertion op will automatically set the appid extension input, and finish assertion op will adjust its verification logic to also accept this AppID as an alternative to the RP ID. By default, this is not set.

org.apereo.cas.configuration.model.support.mfa.webauthn.WebAuthnMultifactorAuthenticationCoreProperties.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.authn.mfa.web-authn.core.application-id=...

CAS properties can be specified using the YAML syntax:

cas: 
  authn: 
    mfa: 
      web-authn: 
        core: 
          application-id: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.authn.mfa.web-authn.core.application-id="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_AUTHN_MFA_WEB_AUTHN_CORE_APPLICATION_ID="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.authn.mfa.web-authn.core.application-id="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

cas.authn.mfa.web-authn.core.relying-party-id=

The id that will be set as the rp parameter when initiating registration operations, and which id hash will be compared against. This is a required parameter. A successful registration or authentication operation requires rp id hash to exactly equal the SHA-256 hash of this id member. Alternatively, it may instead equal the SHA-256 hash of application id if the latter is present.

org.apereo.cas.configuration.model.support.mfa.webauthn.WebAuthnMultifactorAuthenticationCoreProperties.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.authn.mfa.web-authn.core.relying-party-id=...

CAS properties can be specified using the YAML syntax:

cas: 
  authn: 
    mfa: 
      web-authn: 
        core: 
          relying-party-id: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.authn.mfa.web-authn.core.relying-party-id="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_AUTHN_MFA_WEB_AUTHN_CORE_RELYING_PARTY_ID="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.authn.mfa.web-authn.core.relying-party-id="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

cas.authn.mfa.web-authn.core.relying-party-name=

The human-palatable name of the Relaying Party.

org.apereo.cas.configuration.model.support.mfa.webauthn.WebAuthnMultifactorAuthenticationCoreProperties.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.authn.mfa.web-authn.core.relying-party-name=...

CAS properties can be specified using the YAML syntax:

cas: 
  authn: 
    mfa: 
      web-authn: 
        core: 
          relying-party-name: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.authn.mfa.web-authn.core.relying-party-name="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_AUTHN_MFA_WEB_AUTHN_CORE_RELYING_PARTY_NAME="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.authn.mfa.web-authn.core.relying-party-name="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

cas.authn.mfa.web-authn.crypto.encryption.key=

The encryption key is a JWT whose length is defined by the encryption key size setting.

org.apereo.cas.configuration.model.core.util.EncryptionJwtCryptoProperties.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.authn.mfa.web-authn.crypto.encryption.key=...

CAS properties can be specified using the YAML syntax:

cas: 
  authn: 
    mfa: 
      web-authn: 
        crypto: 
          encryption: 
            key: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.authn.mfa.web-authn.crypto.encryption.key="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_AUTHN_MFA_WEB_AUTHN_CRYPTO_ENCRYPTION_KEY="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.authn.mfa.web-authn.crypto.encryption.key="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

cas.authn.mfa.web-authn.crypto.signing.key=

The signing key is a JWT whose length is defined by the signing key size setting.

org.apereo.cas.configuration.model.core.util.SigningJwtCryptoProperties.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

cas.authn.mfa.web-authn.crypto.signing.key=...

CAS properties can be specified using the YAML syntax:

cas: 
  authn: 
    mfa: 
      web-authn: 
        crypto: 
          signing: 
            key: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dcas.authn.mfa.web-authn.crypto.signing.key="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export CAS_AUTHN_MFA_WEB_AUTHN_CRYPTO_SIGNING_KEY="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --cas.authn.mfa.web-authn.crypto.signing.key="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.