SAML2 Dynamic Metadata Management

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

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://"
}
Metadata Location

The metadata location in the registration record above simply needs to be specified as rest:// to signal to CAS that SAML metadata for registered service provider must be fetched from REST endpoints defined in CAS configuration.

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:

Field Description
id The identifier of the record.
name Indexed field which describes and names the metadata briefly.
value The XML document representing the metadata for the service provider.
signature The contents of the signing certificate to validate metadata, if any.

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://"
}
Metadata Location

The metadata location in the registration record above simply needs to be specified as mongodb:// to signal to CAS that SAML metadata for registered service provider must be fetched from MongoDb data sources defined in CAS configuration.

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:

Field Description
id The identifier of the record.
name Indexed field which describes and names the metadata briefly.
value The XML document representing the metadata for the service provider.
signature The contents of the signing certificate to validate metadata, if any.

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://"
}
Metadata Location

The metadata location in the registration record above simply needs to be specified as jdbc:// to signal to CAS that SAML metadata for registered service provider must be fetched from JDBC data sources defined in CAS configuration.

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:

Field Description
id The identifier of the record.
signingCertificate The signing certificate.
signingKey The signing key.
encryptionCertificate The encryption certificate.
encryptionKey The encryption key.
metadata 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.

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:

Field Description
id The identifier of the record.
name Indexed field which describes and names the metadata briefly.
value The XML document representing the metadata for the service provider.
signature The contents of the signing certificate to validate metadata, if any.

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://"
}
Metadata Location

The metadata location in the registration record above simply needs to be specified as couchdb:// to signal to CAS that SAML metadata for registered service provider must be fetched from CouchDb as defined in CAS configuration.

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:

Field Description
id The identifier of the record.
signingCertificate The signing certificate.
signingKey The signing key.
encryptionCertificate The encryption certificate.
encryptionKey The encryption key.
metadata 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.

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:

Parameter Description
registeredService The object representing the corresponding service definition in the registry.
samlConfigBean The object representing the OpenSAML configuration class holding various builder and marshaller factory instances.
samlProperties The object responsible for capturing the CAS SAML IdP properties defined in the configuration.
logger The object responsible for issuing log messages such as logger.info(...).

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:

Parameter Description
signature The metadata signing certificate, if any.
Metadata Location

The metadata location in the registration record above simply needs to be specified as awss3:// to signal to CAS that SAML metadata for registered service provider must be fetched from Amazon S3 defined in CAS configuration.

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:

Field Description
id The identifier of the record.
signingCertificate The signing certificate.
signingKey The signing key.
encryptionCertificate The encryption certificate.
encryptionKey The encryption key.

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.