APEREO CASDocumentation

Enterprise Authentication for All Earthlings and Beyond

Identity, Single Sign-On and Access Management
View on GitHub

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:

health
Third-party endpoint2 operationsExposed by default
1

Turn the endpoint on and expose it over the web. One entry covers every operation. By default only info, health and status are exposed.



1
2



management.endpoint.health.access=UNRESTRICTED
management.endpoints.web.exposure.include=health

Endpoints may be mapped to other paths. For example, to serve health at healthcheck:



1



management.endpoints.web.path-mapping.health=healthcheck

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, kept within a minimum and maximum that are controlled via CAS settings, so that metadata asking to be cached for no time at all is not loaded again on every request.
  2. Metadata expiration policy and duration defined for the SAML2 registered service defined with CAS.
  3. Global metadata expiration policy controlled via CAS settings.

Whichever applies, cached metadata is loaded again once the validUntil of the service provider, or of the aggregate that holds it, has passed, rather than turning requests away as no longer valid until the cache entry expires.

Cached metadata is tied to the metadata settings of the service definition, such as signature validation, filtering criteria or the expiration policy. Once a service definition changes any of those, the next request resolves its metadata again on every CAS node, and the entry built from the previous definition simply expires. Metadata kept in a metadata store or served by a metadata query server is cached per entity.

When metadata cannot be loaded for a service provider, CAS remembers the failure for a short period that is controlled via CAS settings, and requests for that service provider are rejected right away instead of contacting the metadata source every time. A failed HTTP request that fetches metadata may still be retried, again as controlled via CAS settings.

Metadata that is read from files on disk, whether XML files, a directory of metadata files or the JSON file described below, is loaded again once a file changes, even before its cache entry expires. CAS compares the modification times of those files, and the files present in a metadata directory, at most once per interval that is controlled via CAS settings, so a busy server does not inspect the disk on every request.

The cached metadata endpoint reports the metadata of a service along with whether each entity is still valid and, when the entity declares one, its validUntil instant. The endpoint can also list statistics of the cache, such as its size, hit rate and load times, along with every cached entry: the service and entity it was loaded for, when it was loaded and when it expires, the resolvers and local files it came from, the state of its metadata backup file, and the failure remembered for it, if any. The same cache statistics are published as cache.* metrics tagged with cache=samlRegisteredServiceMetadata when metrics are turned on.

samlIdPRegisteredServiceMetadataCache
CAS endpoint3 operationsNot exposed by default
1

Turn the endpoint on and expose it over the web. One entry covers every operation. By default only info, health and status are exposed.



1
2



management.endpoint.samlIdPRegisteredServiceMetadataCache.access=UNRESTRICTED
management.endpoints.web.exposure.include=samlIdPRegisteredServiceMetadataCache

Endpoints may be mapped to other paths. For example, to serve health at healthcheck:



1



management.endpoints.web.path-mapping.health=healthcheck
: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.

    Comma-separated locations are treated as mirrors of the same document: CAS tries each in turn and only falls back onto the backup file once none of them can produce metadata. Downloads are conditional requests based on the ETag and Last-Modified headers of the previous answer, which CAS keeps next to the backup file, so a metadata host that answers 304 Not Modified is not asked to send the document again. When no location works and there is no backup file, the failure names every location and why it failed, such as the HTTP status it answered with.

    Every answer from a metadata location confirms the backup file, whether the location sends the document again or answers that it has not changed. When CAS has to fall back onto a backup file, it logs how long ago the metadata source last confirmed it, and once that is longer than allowed by CAS settings, the fallback is logged as an error and the service is flagged as stale by the metadata health indicator and the cached metadata endpoint. The backup file is still used, so that service providers keep working while the metadata source is restored.

    :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:

    cas.authn.saml-idp.metadata.http.force-metadata-refreshForcefully download and fetch metadata files form URL sources and disregard any cached copies of the metadata.
    true

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

    Type
    Boolean
    Default
    true
    Defined by
    HttpSamlMetadataProperties
    cas.authn.saml-idp.metadata.http.metadata-backup-locationDirectory location where downloaded SAML metadata is cached as backup files.
    no default
    SpEL

    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.

    Type
    String
    Default
    none
    Defined by
    HttpSamlMetadataProperties
    Supports
    Spring Expression Language
    cas.authn.saml-idp.metadata.http.metadata-backup-max-age
    P7D
    Type
    String
    Default
    P7D

    Required settings may be needed to activate or affect the feature; review them even when they have a default. Optional settings only need to be set to change a default or to turn on the behavior they control. Third party settings belong to libraries such as Spring Boot that CAS builds on; their own documentation may have more detail.

    Notes on configuration

    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, especially 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. Changes to a metadata file are picked up without waiting for its cached metadata to expire.

  • 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. The file is read again once it changes, or once it is created after CAS has started, and metadata built from it is loaded again as well. 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.
DynamoDb See this guide.