SAML2 Metadata Management

Management of service provider metadata in a dynamic on-the-fly fashion may be accomplished via strategies outlined here.

Administrative Endpoints

The following endpoints are provided by CAS:

A GET operation produces the cached copy of the metadata for a given service provider, using the serviceId and entityId parameters. The serviceId parameter may be the numeric identifier for the registered service or its name. In case the service definition represents a metadata aggregate such as InCommon, the entityId parameter may be used to pinpoint and filter the exact entity within the aggregate.

A DELETE operation will delete invalidate the metadata cache. If no parameters are provided, the metadata cache will be entirely invalidated. A serviceId parameter will force CAS to only invalidate the cached metadata instance for that service provider. The serviceId parameter may be the numeric identifier for the registered service or its name.

Metadata Query Protocol

CAS also supports the Dynamic Metadata Query Protocol which is a REST-like API for requesting and receiving arbitrary metadata. In order to configure a CAS SAML service to retrieve its metadata from a Metadata query server, the metadata location must be configured to point to the query server instance.

MDQ may be configured using the below snippet as an example:

1
2
3
4
5
6
7
8
{
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-of-the-sp",
  "name" : "SAMLService",
  "id" : 10000003,
  "evaluationOrder" : 10,
  "metadataLocation" : "https://mdq.server.org/entities/{0}"
}

…where {0} serves as an entityID placeholder for which metadata is to be queried. The placeholder is dynamically processed and replaced by CAS at runtime.

REST

Similar to the Dynamic Metadata Query Protocol (MDQ), SAML service provider metadata may also be fetched using a more traditional REST interface. This is a simpler option that does not require one to deploy a compliant MDQ server and provides the flexibility of producing SP metadata using any programming language or framework.

Support is enabled by including the following module in the overlay:

1
2
3
4
5
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-saml-idp-metadata-rest</artifactId>
  <version>${cas.version}</version>
</dependency>

Use the below snippet as an example to fetch metadata from REST endpoints:

1
2
3
4
5
6
7
8
{
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-of-the-sp",
  "name" : "SAMLService",
  "id" : 10000003,
  "evaluationOrder" : 10,
  "metadataLocation" : "rest://"
}

Requests are submitted to REST endpoints with entityId as the parameter and Content-Type: application/xml as the header. Upon a successful 200 - OK response status, CAS expects the body of the HTTP response to match the below snippet:

1
2
3
4
5
6
{  
   "id":1000,
   "name":"SAML Metadata For Service Provider",
   "value":"...",
   "signature":"..."
}

To see the relevant CAS properties, please see this guide.

MongoDb

Metadata documents may also be stored in and fetched from a MongoDb instance. This may specially be used to avoid copying metadata files across CAS nodes in a cluster, particularly where one needs to deal with more than a few bilateral SAML integrations. Metadata documents are stored in and fetched from a single pre-defined collection that is taught to CAS via settings. The outline of the document is as follows:

Support is enabled by including the following module in the overlay:

1
2
3
4
5
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-saml-idp-metadata-mongo</artifactId>
  <version>${cas.version}</version>
</dependency>

SAML service definitions must then be designed as follows to allow CAS to fetch metadata documents from MongoDb instances:

1
2
3
4
5
6
7
8
{
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-of-the-sp",
  "name" : "SAMLService",
  "id" : 10000003,
  "description" : "A MongoDb-based metadata resolver",
  "metadataLocation" : "mongodb://"
}

To see the relevant CAS properties, please see this guide.

Identity Provider Metadata

Metadata artifacts that belong to CAS as a SAML2 identity provider may also be managed and stored via MongoDb. Artifacts such as the metadata, signing and encryption keys, etc are kept inside a MongoDb collection taught to CAS via settings as a single document that would have the following structure:

1
2
3
4
5
6
7
{
    "signingCertificate": "...",
    "signingKey": "...",
    "encryptionCertificate": "...",
    "encryptionKey": "...",
    "metadata": ""
}

Note that the signing and encryption keys are expected to be encrypted and signed using CAS crypto keys. To see the relevant CAS properties, please see this guide.

JPA

Metadata documents may also be stored in and fetched from a relational database instance. This may specially be used to avoid copying metadata files across CAS nodes in a cluster, particularly where one needs to deal with more than a few bilateral SAML integrations. Metadata documents are stored in and fetched from a single pre-defined table (i.e. SamlMetadataDocument) whose connection information is taught to CAS via settings and is automatically generated. The outline of the table is as follows:

Support is enabled by including the following module in the overlay:

1
2
3
4
5
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-saml-idp-metadata-jpa</artifactId>
  <version>${cas.version}</version>
</dependency>

SAML service definitions must then be designed as follows to allow CAS to fetch metadata documents from database instances:

1
2
3
4
5
6
7
8
{
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-of-the-sp",
  "name" : "SAMLService",
  "id" : 10000003,
  "description" : "A relational-db-based metadata resolver",
  "metadataLocation" : "jdbc://"
}

To see the relevant CAS properties, please see this guide.

Identity Provider Metadata

Metadata artifacts that belong to CAS as a SAML2 identity provider may also be managed and stored via JPA. Artifacts such as the metadata, signing and encryption keys, etc are kept inside a database table that would have the following structure:

Note that the signing and encryption keys are expected to be encrypted and signed using CAS crypto keys. To see the relevant CAS properties, please see this guide.

CouchDb

Metadata documents may also be stored in and fetched from a NoSQL database. This may specially be used to avoid copying metadata files across CAS nodes in a cluster, particularly where one needs to deal with more than a few bilateral SAML integrations. Metadata documents are stored in and fetched from a single pre-defined table (i.e. SamlMetadataDocument) whose connection information is taught to CAS via settings and is automatically generated. The outline of the database document is as follows:

Support is enabled by including the following module in the overlay:

1
2
3
4
5
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-saml-idp-metadata-couchdb</artifactId>
  <version>${cas.version}</version>
</dependency>

SAML service definitions must then be designed as follows to allow CAS to fetch metadata documents from CouchDb instances:

1
2
3
4
5
6
7
8
{
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-of-the-sp",
  "name" : "SAMLService",
  "id" : 10000003,
  "description" : "A relational-db-based metadata resolver",
  "metadataLocation" : "couchdb://"
}

Note that the signing and encryption keys are expected to be encrypted and signed using CAS crypto keys. To see the relevant CAS properties, please see this guide.

Identity Provider Metadata

Metadata artifacts that belong to CAS as a SAML2 identity provider may also be managed and stored via CouchDb. Artifacts such as the metadata, signing and encryption keys, etc are kept inside a database with documents that would have the following structure:

Note that the signing and encryption keys are expected to be encrypted and signed using CAS crypto keys. To see the relevant CAS properties, please see this guide.

Groovy

A metadata location for a SAML service definition may point to an external Groovy script, allowing the script to programmatically determine and build the metadata resolution machinery to be added to the collection of the existing resolvers.

1
2
3
4
5
6
7
8
{
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-of-the-sp",
  "name" : "SAMLService",
  "id" : 10000003,
  "description" : "A Groovy-based metadata resolver",
  "metadataLocation" : "file:/etc/cas/config/groovy-metadata.groovy"
}

The outline of the script may be as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import java.util.*
import org.apereo.cas.support.saml.*
import org.apereo.cas.support.saml.services.*
import org.opensaml.saml.metadata.resolver.*

def Collection<MetadataResolver> run(final Object... args) {
    def registeredService = args[0]
    def samlConfigBean = args[1]
    def samlProperties = args[2]
    def logger = args[3]

    /*
     Stuff happens where you build the relevant metadata resolver instance(s).
     When done, simply wrap the results into a collection and return.
     A null or empty collection will be ignored by CAS.
  */
  def metadataResolver = ...
   return CollectionUtils.wrap(metadataResolver)
}

The parameters passed are as follows:

Amazon S3

Metadata documents may also be stored in and fetched from a MongoDb instance. This may specially be used to avoid copying metadata files across CAS nodes in a cluster, particularly where one needs to deal with more than a few bilateral SAML integrations. Metadata documents are stored in and fetched from a single pre-defined bucket that is taught to CAS via settings.

Support is enabled by including the following module in the overlay:

1
2
3
4
5
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-saml-idp-metadata-aws-s3</artifactId>
  <version>${cas.version}</version>
</dependency>

SAML service definitions must then be designed as follows to allow CAS to fetch metadata documents from MongoDb instances:

1
2
3
4
5
6
7
8
{
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-of-the-sp(s)",
  "name" : "SAMLService",
  "id" : 10000003,
  "description" : "Amazon S3-based metadata resolver",
  "metadataLocation" : "awss3://"
}

The following parameters are expected for the Amazon S3 object metadata:

To see the relevant CAS properties, please see this guide.

Identity Provider Metadata

Metadata artifacts that belong to CAS as a SAML2 identity provider may also be managed and stored via Amazon S3 buckets. Artifacts such as the metadata, signing and encryption keys, etc are kept inside a bucket with metadata that would have the following structure:

The actual object’s content/body is expected to contain the SAML2 identity provider metadata. Note that the signing and encryption keys are expected to be encrypted and signed using CAS crypto keys.

To see the relevant CAS properties, please see this guide.