CAS X.509 authentication provides a mechanism to authenticate users who present client certificates during the SSL/TLS handshake process. This means that during your initial attempt to communicate with a CAS server over a secure connection, the server may request a Certificate from your web browser, asking for proof that you are who you claim to be. Known as “Client Authentication”, this behavior can be altered in a few ways to either force X.509 client authentication, let it be optional, or allow the user to make the choice.

This tutorial specifically requires and focuses on:

• CAS 6.3.x
• Java 11
• CAS WAR Overlay

Primary Authentication

A user may install any number of certificates into the browser from any number of CA’s. If only one of these certificates comes from a CA named in the list of acceptable CA’s sent by the server, then most browsers will automatically send that one certificate without asking, and some can be configured to not ask when there is only one possible choice. This presents a user experience where CAS becomes transparent to the user after some initial setup and the login happens automatically.

Once X.509 extension module is configured with CAS, the embedded Apache Tomcat container backed by Spring Boot can be configured to prompt the browser for certificates and client authentication. This is usually achieved via the following settings:

server:
    port: 8443
    ssl:
        # The trust store settings required by X.509
        trust-store: file:/opt/cas/truststore.jks
        trust-store-password: changeit
        client-auth: need

X.509 authentication requires a truststore that contains valid certificates. You can import certificates into this keystore using the following command:

$JAVA_HOME/bin/keytool -import -alias <alias> -keystore /opt/cas/truststore.jks -file <cert-file>

You can choose the password you prefer (i.e. changeit), as long as you also configure it in the settings. You can specify an alias for a friendly name inside the store, and the path to the certificate.

The embedded Apache Tomcat container is also configured to use need for certificate authentication. This means that client authentication with X.509 is requested and mandatory. If the browser can provide a certificate to CAS, then X.509 authentication will take place. If no certificate is available, then authentication does fail.

Unlimited Certificate Path

If you do encounter the error message Unlimited certificate path length not allowed by configuration., be sure to adjust your CAS configuration to match the following:

cas:
    authn:
        x509:
            max-path-length: 2147483647
            max-path-length-allow-unspecified: true

Fallback Authentication

It is possible to configure the embedded Apache Tomcat container to make X.509 optional, letting CAS opt back into its normal authentication flow.

server:
    ssl:
        client-auth: want

This setting means that client authentication with X.509 is required but it is not mandatory. If the browser can provide a certificate to CAS, then X.509 authentication will take place. If no certificate is available, then X.509 is skipped and CAS will proceed with its normal authentication flow.

Optional X.509

So far, the configuration of X.509 client authentication is backed by Spring Boot and affects the entire CAS deployment preemptively. X.509 authentication is a step that primarily and initially happens between the web server and the browser before CAS can have a chance to negotiate options and tune behavior. This presents difficulties in scenarios where you may want to allow the user to select either X.509 authentication or the usual CAS login flow without first being prompted for certificates, etc. In this scenario, the user is allowed the option to select a login flow via X.509 at which time the browser would present a dialog prompt asking for a certificate selection and then passing it onto CAS to proceed.

This use case can be achieved by exposing a dedicated port for the embedded Apache Tomcat container that may forcefully require X.509 authentication upon access.

cas.authn.x509.webflow.port=8446

Doing so should automatically allow for an extra login option in the user interface to trigger the browser for X.509:

Need Help?

If you have questions about the contents and the topic of this blog post, or if you need additional guidance and support, feel free to send us a note and ask about consulting and support services.

So…

I hope this review was of some help to you and I am sure that both this post as well as the functionality it attempts to explain can be improved in any number of ways. Please feel free to [engage and contribute][contribguide] as best as you can.

Happy Coding,

Misagh Moayyed