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:

Endpoint Description
samlIdPRegisteredServiceMetadataCache Manage and control the cache that holds metadata instances for SAML service providers. Note the cache is specific to the JVM memory of the CAS server node and it’s NOT distributed or replicated. 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:

implementation "org.apereo.cas:cas-server-support-saml-idp-metadata-rest:${project.'cas.version'}"
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-saml-idp-metadata-rest</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-saml-idp-metadata-rest"
}

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 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":"..."
}

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 may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

  • cas.authn.saml-idp.metadata.rest.crypto.encryption.key=

    • The encryption key is a JWT whose length is defined by the signing key size setting.

  • cas.authn.saml-idp.metadata.rest.crypto.signing.key=

    • The signing key is a JWT whose length is defined by the signing key size setting.

  • cas.authn.saml-idp.metadata.rest.url=

    • The endpoint URL to contact and retrieve attributes.

    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.saml-idp.metadata.rest.crypto.alg=

    • The signing/encryption algorithm to use.

  • cas.authn.saml-idp.metadata.rest.crypto.enabled=true

    • Whether crypto operations are enabled.

  • cas.authn.saml-idp.metadata.rest.crypto.encryption.key-size=512

    • The encryption key size.

  • cas.authn.saml-idp.metadata.rest.crypto.signing.key-size=512

    • The signing key size.

  • cas.authn.saml-idp.metadata.rest.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.
  • cas.authn.saml-idp.metadata.rest.basic-auth-password=

    • If REST endpoint is protected via basic authentication, specify the password for authentication.

  • cas.authn.saml-idp.metadata.rest.basic-auth-username=

    • If REST endpoint is protected via basic authentication, specify the username for authentication.

  • cas.authn.saml-idp.metadata.rest.idp-metadata-enabled=false

    • Whether identity provider metadata artifacts are expected to be found in the database.

  • cas.authn.saml-idp.metadata.rest.method=GET

    • HTTP method to use when contacting the rest endpoint. Examples include GET, POST, etc.