Apereo CAS deployments typically tend to manage SSO sessions using browser cookies. This cookie maintains a login state for the client, and while it is valid, the client can present it to CAS instead of primary credentials. To protect this cookie, CAS offers a variety of options and strategies to sign and encrypt this cookie and optionally pin it to a specific client session that is usually identified by a user agent, IP address, or, in more advanced scenarios, the client’s geographical location.

In this post, we will review a number of these options with a specific focus on linking SSO sessions to geographical locations. Our starting position is as follows:

• CAS 7.0.x
• Java 21

Cookie Security

The SSO cookie, also known as the ticket-granting cookie (TGC) is an HTTP cookie set by CAS upon the establishment of a single sign-on session. By default, the cookie value is linked to the active user’s active authentication attempt, the remote IP address that initiated the request as well as the user agent that submitted the request. Furthermore, this cookie is automatically scoped to the appropriate domain, and context path, and is marked to be both Secure and HttpOnly.

• Secure: A cookie with the Secure attribute is only sent to the server with an encrypted request over the HTTPS protocol. It’s never sent with unsecured HTTP (except on localhost), which means man-in-the-middle attackers can’t access it easily.

• HttpOnly: A cookie with the HttpOnly` attribute is inaccessible to the JavaScript Document.cookie API; it’s only sent to the server. This precaution helps mitigate cross-site scripting (XSS) attacks.

The final cookie value is then encrypted and signed by appropriate security keys. These keys MUST be regenerated per your specific environment. Each key is a JSON Web Token with a defined length per the algorithm used for encryption and signing.

cas.tgc.crypto.encryption.key=...
cas.tgc.crypto.signing.key=...

If keys are not generated by the deployer and are left blank (which typically is the default case on startup), CAS will attempt to auto-generate keys and will output the result for each respected key. The deployer MUST attempt to copy the generated keys over to the appropriate settings in their CAS properties file, especially when running a multi-node CAS deployment. Failure to do so will prevent CAS from decrypting and encrypting the cookie value and will stop successful single sign-on attempts.

Session Pinning

By default, the cookie value is linked to the active user’s active authentication attempt, the remote IP address that initiated the request as well as the user agent that submitted the request. This behavior is controlled via:

cas.tgc.pin-to-session=false

One particular side-effect of this behavior might be that if users tend to switch IP addresses and networks via VPN software often, their SSO session would be invalidated on each authentication attempt and CAS would prompt them to enter credentials again. Aside from turning off session pinning, one alternative would be to teach patterns of known IP addresses to CAS. If a change in the client IP address is detected, the setting would allow CAS to recognize and authorize the IP addresses for the current SSO session:

cas.tgc.allowed-ip-addresses-pattern=...

This is a regular expression pattern that indicates the set of allowed IP addresses. As stated before, if there is a mismatch between the cookie IP address and the current request-provided IP address (i.e. network switches, VPN, etc), the cookie can still be considered valid if the new IP address matches the pattern specified here.

Geolocating Sessions

Another possibility would be to allow CAS to geolocate the client’s IP address and pin the cookie to a location rather than an IP address. This option would require a valid subscription to a geolocation service such as MaxMind.

According to the MaxMind website:

MaxMind GeoIP2 offerings identify the location and other characteristics of Internet users for a wide range of applications including content personalization, fraud detection, ad targeting, traffic analysis, compliance, geo-targeting, geo-fencing, and digital rights management.

To activate this variant of session pinning, one would need to tweak a CAS build with the right extension module and configure CAS to integrate with MaxMind. Once ready, the geolocation of client sessions can be turned on using the following:

cas.tgc.geo-locate-client-session=true

Using this option, client sessions using the client IP address are geo-located via MaxMind. The resulting session is either pinned to the client geolocation, or the default client address if no geolocation can be found.

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 as best as you can.

Happy Coding,

Misagh Moayyed