SAML2 Service Provider Metadata

This document describes how SAML2 service providers registered with CAS can control their certain aspects of their metadata management.

Actuator Endpoints

The following endpoints are provided by CAS:

 Reports back general health status of the system, produced by various monitors.

 Reports back general health status of the system, produced by various monitors.


Metadata Aggregates

CAS services are fundamentally recognized and loaded by service identifiers taught to CAS typically via regular expressions. This allows for common groupings of applications and services by url patterns (i.e. “Everything that belongs to example.org is registered with CAS). With aggregated metadata, CAS essentially does double authorization checks because it will first attempt to find the entity id in its collection of resolved metadata components and then it looks to see if that entity id is authorized via the pattern that is assigned to that service definition. This means you can do one of several things:

  1. Open up the pattern to allow everything that is authorized in the metadata.
  2. Restrict the pattern to only a select few entity ids found in the metadata. This is essentially the same thing as defining metadata criteria to filter down the list of resolved relying parties and entity ids except that its done after the fact once the metadata is fully loaded and parsed.
  3. You can also instruct CAS to filter metadata entities by a defined criteria at resolution time when it reads the metadata itself. This is essentially the same thing as forcing the pattern to match entity ids, except that it’s done while CAS is reading the metadata and thus load times are improved.

Metadata Caching & Resolution

Service provider metadata is fetched and loaded on demand for every service and then cached in a global cache for a configurable duration. Subsequent requests for service metadata will always consult the cache first and if missed, will resort to actually resolving the metadata by loading or contacting the configured resource.

Each service provider definition that is registered with CAS may optionally also specifically an expiration period of metadata resolution to override the default global value.

The expiration policy of the service metadata is controlled using the following order:

  1. CacheDuration setting found inside the SAML2 service provider metadata, if any.
  2. Metadata expiration policy and duration defined for the SAML2 registered service defined with CAS.
  3. Global metadata expiration policy controlled via CAS settings.

 Invalidate SAML2 metadata cache using a service id or entity id. The service id could be the registered service numeric identifier, its name or actual service id. In case the service definition points to an aggregate, you may also specify an entity id to locate the service provider within that aggregate. If you do not specify any parameters, all entries in the metadata cache will be invalidated.

 Get SAML2 cached metadata for a SAML2 registered service. The service id could be the registered service numeric identifier, its name or actual service id. In case the service definition points to an aggregate, you may also specify an entity id to locate the service provider within that aggregate.


:information_source: Metadata Cache

Note that the state of the cache belongs to the CAS server node's own memory and will not distributed in case you have multiple CAS server nodes in a cluster. In an HA clustered environment, you would need to bypass load balancers, etc to reach the actual CAS server node(s) before the cache can be accessed. Otherwise, you run the risk of manipulating and interacting with the metadata cache managed by one CAS server where metadata caches changes would be unseen by other CAS servers, until and unless their own cached entries are either forcefully removed or expire.

Metadata Storage

SAML2 service providers that are registered with CAS can be configured to present their metadata using the following options.

Default

If the SAML2 service provider is able to produce valid metadata, you may register the metadata with CAS as either a URL or a path to the metadata XML file or a classpath resource noted by the appropriate prefix. Using this model, CAS will consume the metadata directly from a published URL and/or XML file on disk, and may optionally be allowed to verify the signature of the metadata as necessary.

Metadata location can use the Spring Expression Language syntax.

  • 

    1
2
3
4
5
6
7

    		

    {
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-of-the-sp",
  "name" : "SAMLService",
  "id" : 1,
  "metadataLocation" : "https://url/to/metadata.xml"
}

    Multiple locations may be comma-separated. CAS may attempt to reuse the metadata from a previously-downloaded backup file on disk if the metadata file is still seen as valid. This capability will require the forceful fetching of the metadata over HTTP to be disabled.

    :information_source: Usage

    SAML2 metadata should generally be signed for integrity and authenticity, especially if it’s provided and shared with participants using a URL. Participants and consumers are strongly encouraged to verify the XML signature on the metadata file before use; failure to do so will seriously compromise the security of the SAML deployment. A trusted metadata process MUST verify the XML signature of the metadata. It is not sufficient to request the metadata via a TLS-protected HTTP connection.

    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.

    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. In other words, you should only include this field in your configuration if you need to modify the default value or if you need to turn on the feature controlled by the setting.

  • cas.authn.saml-idp.metadata.http.force-metadata-refresh=true

    • Forcefully download and fetch metadata files form URL sources and disregard any cached copies of the metadata.

    org.apereo.cas.configuration.model.support.saml.idp.metadata.HttpSamlMetadataProperties.

    How can I configure this property?

  • cas.authn.saml-idp.metadata.http.metadata-backup-location=

    • Directory location where downloaded SAML metadata is cached as backup files. If left undefined, the directory is calculated off of the metadata location on disk when specified. The directory location should also support and be resolvable via Spring expression language.

    This setting supports the Spring Expression Language.

    org.apereo.cas.configuration.model.support.saml.idp.metadata.HttpSamlMetadataProperties.

    How can I configure this property?

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc.

    :information_source: Note

    When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

    Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

  • Metadata files for SAML2 service providers can be found on the file system directly:

    

    1
2
3
4
5
6
7

    		

    {
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "the-entity-id-of-the-sp",
  "name" : "SAMLService",
  "id" : 1,
  "metadataLocation" : "/path/to/metadata.xml"
}

    Multiple locations may be comma-separated.

  • This option fetches metadata from a local directory source as needed. You are responsible for populating the directory with metadata files, which may be done while CAS is running. New metadata will be seen automatically the first time it is requested.

    

    1
2
3
4
5
6
7

    		

    {
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : ".+",
  "name" : "SAMLService",
  "id" : 1,
  "metadataLocation" : "/path/to/metadata/directory"
}

    Metadata files in the specified directory location must be stored as the lower case hex-encoded SHA-1 digest of the service provider entity id suffixed with .xml. For example, a service provider with the entity id sp1:example should be stored in as 3494744350abe1fd8efa68c5e2696dbbdca4c33a.xml.

Dynamic Metadata

If the SP you wish to integrate with does not produce SAML metadata, you may be able to use this service to create the metadata, save it in an XML file and then reference and register it with CAS for the SP.

Alternatively, you may take advantage of a standalone saml-sp-metadata.json file that may be found in the same directory as the CAS metadata artifacts. The contents of this file, may be defined with a rather relaxed JSON syntax, and may be as follows:



1
2
3
4
5
6
7
8



{
  "https://example.org/saml": {
    "entityId": "https://example.org/saml",
    "certificate": "MIIDUj...",
    "assertionConsumerServiceUrl": "https://example.org/sso/",
    "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  }
}

Each entry in the file is identified by the service provider entity id, allowing CAS to dynamically locate and build the required metadata on the fly to resume the authentication flow. This may prove easier for those service providers that only present a URL and a signing certificate for the integration relieving you from creating and managing XML metadata files separately.

The service providers are registered with the CAS service registry as such:



1
2
3
4
5
6
7



{
  "@class" : "org.apereo.cas.support.saml.services.SamlRegisteredService",
  "serviceId" : "https://example.org/saml",
  "name" : "SAMLService",
  "id" : 10000003,
  "metadataLocation" : "json://"
}
:information_source: Metadata Location

The metadata location in the registration record above needs to be specified as json:// to signal to CAS that SAML metadata for registered service provider must be fetched from the designated JSON file.

Advanced

Service provider metadata can also be managed using any one of the following strategies.

Storage Description
Metadata Query Protocol See this guide.
HTTP/HTTPS See this guide.
REST See this guide.
Git See this guide.
MongoDb See this guide.
Redis See this guide.
JPA See this guide.
Groovy See this guide.
Amazon S3 See this guide.