Overview

One of the more recent additions to CAS, as a SAML2 identity provider, is the ability to override the identity provider metadata and keys on a per-service basis. This capability has been extended to support all identity provider metadata sources and storage services beyond the typical file system. To keep things simple in this blog post, we are going to focus on a sample SAML2 service provider integration backed by CAS as a SAML2 identity provider whose metadata (and all other overrides) are managed by the filesystem.

Our starting position is based on:

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

The Basics

Start with the CAS Overlay, clone the project and follow the notes here to get CAS acting as SAML2 identity provider. In its simplest form, it comes to down to the following settings:

cas.authn.samlIdp.entityId=https://sso.example.org/idp
cas.authn.samlIdp.scope=example.org
cas.authn.samlIdp.metadata.location=file:/etc/cas/config/saml

…and this module in the CAS build:

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

Note how identity provider artifacts such as metadata and keys are backed by the filesystem and stored inside the /etc/cas/config/saml:

$ ls /etc/cas/saml/ 

Permissions Size User   Group Date Modified Name 
-------------------------------------------------
.rw-r--r--  1.1k Misagh wheel  1 Dec 17:45  idp-encryption.crt
.rw-r--r--  1.7k Misagh wheel  1 Dec 17:45  idp-encryption.key
.rw-r--r--  8.1k Misagh wheel  1 Dec 17:45  idp-metadata.xml
.rw-r--r--  1.1k Misagh wheel  1 Dec 17:45  idp-signing.crt
.rw-r--r--  1.7k Misagh wheel  1 Dec 17:45  idp-signing.key

Next, we could use JSON service registry to manage our SAML2 service provider definitions. Here is what our service definition might look like for SAML2 service provider in a SAML-1.json file:

{
  "@class": "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId": "sp.example.org",
  "name": "Example",
  "id": 1,
  "evaluationOrder": 1,
  "metadataLocation": "/sample/metadata/sp-metadata.xml"
}      

Overrides

Let’s say our service provider wanted to use a different set of signing keys, encryption keys or metadata completely separate from the global SAML2 artifacts listed above. Since we are using the filesystem, these overriding artifacts are expected to be found at /etc/cas/config/saml/Example. The formula is, you should create a directory using the name of your service definition (i.e. Example) and this directly should be created inside the canonical global SAML2 metadata directory.

$ tree /etc/cas/saml/
/etc/cas/saml/
├── Example
│   ├── idp-encryption.crt
│   ├── idp-encryption.key
│   ├── idp-metadata.xml
│   ├── idp-signing.crt
│   └── idp-signing.key
├── idp-encryption.crt
├── idp-encryption.key
├── idp-metadata.xml
├── idp-signing.crt
└── idp-signing.key

Note that you do not have to override every single certificate and/or artifact. Depending on the use case, you may be quite selective in choosing the appropriate file for overrides. The bottom line is, if an override is found for a service provider it would be used in combination with everything else. If there are no overrides, then the global artifact would be used for the requested operation.

Furthermore, note that the /idp/metadata endpoint does also accept a service parameter either by entity id or numeric identifier. This parameter is matched against the CAS service registry allowing the endpoint to calculate and combine any identity provider metadata overrides that may have been specified.

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 know that all other use cases, scenarios, features, and theories certainly are possible as well. Feel free to engage and contribute as best as you can.

Finally, if you benefit from Apereo CAS as free and open-source software, we invite you to join the Apereo Foundation and financially support the project at a capacity that best suits your deployment. If you consider your CAS deployment to be a critical part of the identity and access management ecosystem and care about its long-term success and sustainability, this is a viable option to consider.

Happy Coding,

Misagh Moayyed