JWT Service Tickets

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties. CAS may also be allowed to fully create signed/encrypted JWTs and pass them back to the application in form of service tickets.

JWTs are entirely self-contained and contain the authenticated principal as well as all authorized attributes in form of JWT claims.

JCE Requirement

Make sure you have the proper JCE bundle installed in your Java environment that is used by CAS, specially if you need to use specific signing/encryption algorithms and methods. Be sure to pick the right version of the JCE for your Java version. Java versions can be detected via the java -version command.

Overview

JWT-based service tickets are issued to application 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.

All JWTs are by default signed and encrypted by CAS based on keys generated and controlled during deployment. Such keys may be exchanged with client applications to unpack the JWT and access claims.

Flow Diagram

CAS Web flow JWT diagram

Note that per the above diagram, the JWT request by default internally causes CAS to generate an ST for the application and immediately then validate it in order to get access to the authenticated principal and attributes per policies associated with the application registration record in the CAS service registry. This response is transformed into a JWT that is then passed onto the client application.

In other words, the responsibility of receiving a service ticket (ST) and validating it is all moved into and handled internally by CAS. The application only needs to learn how to decipher and unpack the final JWT and ensure its validity.

The expiration time of the generated JWT is controlled by the length of the assertion returned as part of the validation event. If the assertion validity length is not specified, then the expiration time is controlled by the length of the SSO session defined as part of SSO expiration policy of the CAS server.

Not OpenID Connect

Remember that you are just receiving a ticket in form of a JWT, thereby removing the need from your client to validate a normal service ticket. The ticket is internally validated by CAS and you as the client are only left in charge of validating the JWT itself. Do not confuse this with OpenID Connect. While a JWT, the token itself is not an ID token, cannot be refreshed and must be obtained again once you deem it expired. If you need more, consider using the OpenID Connect protocol instead. Note that the responsibility of validating the JWT is pushed onto the client and NOT the CAS server itself.

Administrative Endpoints

The following endpoints are provided by CAS:

Endpoint Description
jwtTicketSigningPublicKey Exposes the signing public key, accepting an optional service parameter.

Configuration

JWT support is enabled by including the following dependency in the WAR overlay:

implementation "org.apereo.cas:cas-server-support-token-tickets:${project.'cas.version'}"
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-token-tickets</artifactId>
  <version>${cas.version}</version>
</dependency>
dependencyManagement {
  imports {
    mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
  }
}

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

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 is not strictly necessary in the end-user CAS configuration, because a default value may be assigned or the feature in question may not be immediately intended for use. You may want to own the setting and update it assigned value, assuming the intended feature controlled by the setting is utilized.

  • cas.authn.token.principal-transformation.groovy.location=
  • The location of the resource. Resources can be URLS, or files found either on the classpath or outside somewhere in the file system.

  • cas.authn.token.crypto.encryption.key=
  • The encryption key is a JWT whose length is defined by the signing key size setting.

  • cas.authn.token.crypto.signing.key=
  • The signing key is a JWT whose length is defined by the signing key size setting.

    The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

  • cas.authn.token.webflow.order=0
  • The order in which the webflow is configured.

  • cas.authn.token.name=
  • Name of the authentication handler.

  • cas.authn.token.principal-transformation.blocking-pattern=
  • A regular expression that will be used against the username to match for blocking/forbidden values. If a match is found, an exception will be thrown and principal transformation will fail.

  • cas.authn.token.principal-transformation.case-conversion=
  • Indicate whether the principal identifier should be transformed into upper-case, lower-case, etc.NONE:No conversion..LOWERCASE:Lowercase conversion..UPPERCASE:Uppercase conversion..

  • cas.authn.token.principal-transformation.pattern=
  • A regular expression that will be used against the provided username for username extractions. On a successful match, the first matched group in the pattern will be used as the extracted username.

  • cas.authn.token.principal-transformation.prefix=
  • Prefix to add to the principal id prior to authentication.

  • cas.authn.token.principal-transformation.suffix=
  • Suffix to add to the principal id prior to authentication.

  • cas.authn.token.crypto.alg=
  • The signing/encryption algorithm to use.

  • cas.authn.token.crypto.enabled=true
  • Whether crypto operations are enabled.

  • cas.authn.token.crypto.encryption-enabled=true
  • Whether crypto encryption operations are enabled.

  • cas.authn.token.crypto.encryption.key-size=512
  • The encryption key size.

  • cas.authn.token.crypto.signing-enabled=true
  • Whether crypto signing operations are enabled.

  • cas.authn.token.crypto.signing.key-size=512
  • The signing key size.

  • cas.authn.token.crypto.strategy-type=ENCRYPT_AND_SIGN
  • Control the cipher sequence of operations. The accepted values are:

    • ENCRYPT_AND_SIGN: Encrypt the value first, and then sign.
    • SIGN_AND_ENCRYPT: Sign the value first, and then encrypt.