JWT Of All Things With CAS


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.

Apereo CAS has had built-in support for JWTs for some time now in a variety of different ways. Notions of JWT support really date back to CAS 3.5.x with the work @epierce did as a CAS extension to enable token authentication support. Since then, support for JWTs has significantly improved and grown over the years and continues to get better with an emerging number of use cases whose chief concern is improving performance and removing round-trip calls, among other things.

In this tutorial, I am going to briefly review various forms of JWT functionality in CAS. Specifically, the following topics will be reviewed:

Environment

  • Apereo CAS 5.2.0-SNAPSHOT
  • curl 7.54.0

…and last but not least, a functional vanilla CAS overlay. For this tutorial, I am using the CAS Maven WAR Overlay project.

JWT Authentication

CAS provides support for token-based authentication on top of JWTs, where an authentication request can be granted an SSO session based on a form of credentials that are JWTs. CAS expects a token parameter (or request header) to be passed along to the /login endpoint as the credential. The parameter value must of course be a JWT.

Let There Be JWT

To generate a JWT, I ended up using the CAS Command-line Shell:

cd cas-overlay-template
./build.sh cli -sh

This will allow you to enter the interactive shell, where you have documentation, tab-completion and history for all commands.

Welcome to CAS Command-line Shell. For assistance press or type "help" then hit ENTER.
cas>

cas>generate-jwt --subject Misagh

==== Signing Secret ====
MY4Jpxr5VeZsJ...

==== Encryption Secret ====
MZCjxBbDFq9cHPdy...

Generating JWT for subject [Misagh] with signing key size [256], signing algorithm [HS256],
    encryption key size [48], encryption method [A192CBC-HS384] and encryption algorithm [dir]

==== JWT ====
eyJjdHkiOiJKV1QiLCJ...

Hooray! We have a JWT.

There are a variety of other parameters such as encryption methods and signing algorithms you can choose from to generate the JWT. For the purposes of this tutorial, let’s keep things simple. Of course, you don’t have to use the CAS command-line shell. Any valid compliant JWT generator would do fine.

Don't Take Things Literally
I am abbreviating the secrets and the generated JWT above. Do NOT copy paste these into your environment and configuration, thinking they might do the trick.

Configure Application

CAS needs to be taught the security properties of the JWT to unpack and validate it and produce the relevant authenticated session. For a given authentication request, CAS will try to find the matching record for the application in its registry that is capable of validating JWTs. If such a record is found and the request is in fact accompanied by JWT credentials, the credential is validated and the service ticket issued.

My CAS overlay is already equipped with the relevant configuration module and my application record using the JSON service registry looks something like this:

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "https://www.example.org",
  "name" : "Example",
  "id" : 1000,
  "properties" : {
    "@class" : "java.util.HashMap",
    "jwtSigningSecret" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "MY4Jpxr5VeZsJ..." ] ]
    },
    "jwtEncryptionSecret" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "MZCjxBbDFq9cHPdy..." ] ]
    }
  }
}

Now, we are ready to start sending requests.

Authenticate

Using curl from a terminal, here is the authentication sequence:

$ curl -i "https://mmoayyed.example.net/cas/login?service=https://www.example.org&token=eyJjdHkiOiJKV1QiLCJ..."

HTTP/1.1 302
...
Location: https://www.example.org?ticket=ST-1-zmEt1zfAuHv9vG6DogfBeH5ylmc-mmoayyed-4
...

A few things to note:

  • The -i option allows curl to output the response headers where Location in the above case contains the redirect URL with the issued service ticket.
  • The entire url in the curl command in encased in double-quotes. This is necessary for curl to ensure the query string is entirely passed along to CAS.

Of course, I can pass the JWT as a request header too:

$ curl -i "https://mmoayyed.example.net/cas/login?service=https://www.example.org" --header "token:eyJjdHkiOiJKV1QiLCJ..."

HTTP/1.1 302
...
Location: https://www.example.org?ticket=ST-1-qamgyzfAuHv9vG6DogfBeH5ylmc-mmoayyed-4
...

Grab the ticket from the Location header and proceed to validate it, as you would any regular service ticket.

Duo Security MFA With JWTs

I want to be able to use my JWT to authenticate with CAS and get a service ticket issued to my application at https://www.example.org, but I also want the request to be verified via second-factor credentials and an MFA flow provided by Duo Security. How do I do that?

Duo Security integration support of CAS is able to also support non-browser based multifactor authentication requests. In order to trigger this behavior, applications (i.e. curl, REST APIs, etc.) need to specify a special Content-Type to signal to CAS that the request is submitted from a non-web based environment. The multifactor authentication request is submitted to Duo Security in auto mode which effectively may translate into an out-of-band factor (push or phone) recommended by Duo as the best for the user’s devices.

YMMV
If you are using a different kind of multifactor authentication provider, you will need to verify whether it's able to support such behaviors.

Configure Duo Security

My overlay is prepped with the relevant configuration module of course and settings that include integration keys, secret keys, etc.

Application MFA Trigger

I am also going to configure an application-based trigger for https://www.example.org so that authentication requests are routed to the relevant multifactor authentication provider.

So my application record will take on the following form:

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "https://www.example.org",
  "name" : "Example",
  "id" : 1000,
  "multifactorPolicy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceMultifactorPolicy",
    "multifactorAuthenticationProviders" : [ "java.util.LinkedHashSet", [ "mfa-duo" ] ]
  }
  "properties" : {
    "@class" : "java.util.HashMap",
    "jwtSigningSecret" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "MY4Jpxr5VeZsJ..." ] ]
    },
    "jwtEncryptionSecret" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "MZCjxBbDFq9cHPdy..." ] ]
    }
  }
}

Authenticate

Using curl again from a terminal, here is the authentication sequence:

$ curl -i "https://mmoayyed.example.net/cas/login?service=https://www.example.org"
    --header "token:eyJjdHkiOiJKV1QiLCJ..." --header "Content-Type: application/cas"

HTTP/1.1 302
...
Location: https://www.example.org?ticket=ST-1-gdfe1zfAuHv9vG6DogfBeH5ylmc-mmoayyed-4
...

Things work exactly the same as before, except that this time your device registered with Duo Security will receive a notification where your approval will authorize CAS to establish a session and generate a ticket.

JWT Service Tickets

All operations so far have issued a regular service ticket back to the application that must be validated in a subsequent trip so the application can retrieve the authenticated user profile. In a different variation, it’s possible for the service ticket itself to take on the form of a JWT. JWT-based service tickets are issued to applications based on the same semantics defined by the CAS Protocol. CAS having received an authentication request via its /login endpoint will conditionally issue back JWT service tickets to the application in form of a ticket parameter via the requested http method.

Let's REST
In case you are using the CAS REST APIs, you should know that service tickets issued as part of REST API operations may also be JWTs.

Configure JWTs

In order for CAS to transform service tickets into JWTs, essentially we need to execute the reverse of the above configuration steps. We will need to ensure CAS is provided with relevant keys to generate JWTs and these keys are in turn used by the application to unpack the JWTness of generated service ticket.

The overlay also needs to be equipped with the relevant extension module of course to allow for this functionality.

You may generate the required secrets manually per the above link. In this example, I left them undefined in my properties which forces CAS to generate a few on its own and warn me about them when it starts up:

... - <Secret key for encryption is not defined for [Token/JWT Tickets]; 
    CAS will attempt to auto-generate the encryption key>
... - <Generated encryption key [...] of size [256] for [Token/JWT Tickets]. 
    The generated key MUST be added to CAS settings under setting [cas.authn.token.crypto.encryption.key].>
... - <Secret key for signing is not defined for [Token/JWT Tickets]. 
    CAS will attempt to auto-generate the signing key>
... - <Generated signing key [...] of size [512] for [Token/JWT Tickets]. 
    The generated key MUST be added to CAS settings under setting [cas.authn.token.crypto.signing.key].>

Fine! Let’s proceed.

Configure Application

JWTs as service tickets are issued on a per-application basis. This means that once CAS finds a matching record for the application in its registry, it will try to determine if the application requires JWTs as service tickets. So my application record will take on the following form:

{
  "@class" : "org.apereo.cas.services.RegexRegisteredService",
  "serviceId" : "https://www.example.org",
  "name" : "Example",
  "id" : 1000,
  "multifactorPolicy" : {
    "@class" : "org.apereo.cas.services.DefaultRegisteredServiceMultifactorPolicy",
    "multifactorAuthenticationProviders" : [ "java.util.LinkedHashSet", [ "mfa-duo" ] ]
  }
  "properties" : {
    "@class" : "java.util.HashMap",
    "jwtSigningSecret" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "MY4Jpxr5VeZsJ..." ] ]
    },
    "jwtEncryptionSecret" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "MZCjxBbDFq9cHPdy..." ] ]
    },
    "jwtAsResponse" : {
      "@class" : "org.apereo.cas.services.DefaultRegisteredServiceProperty",
      "values" : [ "java.util.HashSet", [ "true" ] ]
    }
  }
}

Now, we are ready to start sending requests.

Authenticate

Using curl again from a terminal, here is the authentication sequence:

$ curl -i "https://mmoayyed.example.net/cas/login?service=https://www.example.org" 
    --header "token:eyJjdHkiOiJKV1QiLCJ..." --header "Content-Type: application/cas"

HTTP/1.1 302
...
Location: https://www.example.org?ticket=eyJhbGciOiJIUzUxMiJ9.WlhsS05tRllRV2xQYVVwRlVsV...
...

This works exactly the same as before, except that now the ticket parameter contains a JWT as a service ticket.

Summary

I hope this tutorial was of some help to you. As you have been reading, I can guess that you have come up with a number of missing bits and pieces that would satisfy your JWT needs more comprehensively with CAS. In a way, that is exactly what this tutorial intends to inspire. Please feel free to engage and contribute as best as you can.

Misagh Moayyed

Related Posts

CAS 5.3.0 RC3 Feature Release

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

CAS 5.3.0 RC2 Feature Release

...in which I present an overview of CAS 5.3.0 RC2 release.

CAS 5.2.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.

Link CAS OIDC user to existing Database user

In which we show to link OIDC id to LDAP database user.

CAS Multifactor Authentication with Duo Security

A short walkthrough to demonstrate how one might turn on multifactor authentication with CAS using Duo Security, leveraging a variety of triggers.

Deploying Apereo CAS Behind a Proxy

A short tutorial on how to get Apereo CAS deployed behind proxies and load balancers that aim to terminate SSL.

CAS 5.3.0 RC1 Feature Release

...in which I present an overview of CAS 5.3.0 RC1 release.

Apereo CAS SAML Integration With ADFS

A short tutorial on how to integrate CAS, acting as a SAML identity provider, with ADFS.

Introduction to CAS Commandline Shell

A short review of an interactive command-line shell provided by Apereo CAS.

Multitenancy With CAS

A short review of multitenancy feature variants and equivalents in Apereo CAS.