MetadataManagementBestPractices

In a nutshell, current best practices for the management of SAML metadata include the following specific recommendations:

1. Use FilesystemMetadataProvider or LocalDynamicMetadataProvider for local metadata

2. Use FileBackedHTTPMetadataProvider or DynamicHTTPMetadataProvider for remote metadata

3. Use entity attributes to drive automated relying party configuration (this is called a metadata-driven configuration)

In addition, consider using one or more MetadataFilterPlugins to secure or optimize your configuration; for example the SchemaValidationFilter to ensure your metadata has no obvious errors in it, or the EntityRoleWhiteListFilter to decrease the memory use of the loaded metadata.

The following sections expand on these best practices from the perspective of an IdP deployer.

Contents

Local Metadata

From an IdP perspective, the term local metadata refers to SP metadata under direct control of the IdP operator. More often than not, local metadata is sourced via email or downloaded from a partner web site by clicking a link on a protected web page. Typically local metadata does not expire. Metadata with an expiration date must be refreshed, whereas local metadata is a static resource by definition.

There are two basic approaches to local metadata management:

1. Load metadata in a background thread (using FilesystemMetadataProvider)

2. Load metadata just-in-time as needed (using LocalDynamicMetadataProvider)

FilesystemMetadataProvider

Perhaps the simplest way to manage local metadata is to configure one or more metadata providers of type FilesystemMetadataProvider. As its name implies, a FilesystemMetadataProvider loads (and periodically reloads) metadata from the file system. It does this in a background thread, so that the load operation is invisible to the end user. A simple example follows:

<!--
    Load (and reload) entity metadata from a local file.

    The metadata refresh process is determined by the configured values of the 
    minRefreshDelay attribute (default: PT30S) and maxRefreshDelay attribute 
    (default: PT4H). If you want to load (or reload) the metadata immediately, 
    restart the IdP.
-->
<MetadataProvider id="LocalEntityMetadata" xsi:type="FilesystemMetadataProvider"
                  metadataFile="%{idp.home}/metadata/local-metadata.xml"/>

See the FilesystemMetadataProvider topic for more information.

For IdP deployments with few SP partners, using FilesystemMetadataProvider for local metadata is simple and straightforward. However, since each metadata provider must be configured separately, eventually this approach becomes unmanageable. A more scalable approach leverages a single LocalDynamicMetadataProvider as discussed in the next section.

LocalDynamicMetadataProvider

Using a LocalDynamicMetadataProvider, local metadata is made available to the IdP by simply dropping an entity descriptor into a system directory called the sourceDirectory. As with FilesystemMetadataProvider, no system restart is required either when a file is added to (or removed from) the sourceDirectory. A LocalDynamicMetadataProvider dynamically resolves metadata from the sourceDirectory based on the entityID.

There is, however, some administrative overhead associated with a LocalDynamicMetadataProvider as the files in the sourceDirectory must be suitably named so that the provider can resolve entity metadata as needed. These file operations require tools, either command-line tools or a GUI, none of which are included with the Shibboleth IdP software.

See the LocalDynamicMetadataProvider topic for more information.

Remote Metadata

Remote metadata is loaded from a remote source via an HTTP metadata provider. There are two basic approaches:

1. Out-of-band metadata refresh (using FileBackedHTTPMetadataProvider)

2. In-band metadata query (using DynamicHTTPMetadataProvider)

Metadata refresh and metadata query are commonly used to consume metadata published by a trusted third party called a Federation. There are more than 80 recognized Federations in the R&E sector worldwide.

SAML metadata contains the public keys of federation partners, and so the distribution of metadata constitutes a public key infrastructure (PKI) for SAML deployments.

To obtain the latest set of trusted public keys, metadata must be kept current. To encourage reloading, remote metadata has an expiration date (@validUntil) and/or a cache directive (@cacheDuration). The latter is merely a hint but metadata expiration is absolute, so monitor your remote sources carefully.

FileBackedHTTPMetadataProvider

A FileBackedHTTPMetadataProvider will load (and periodically reload) a metadata file from an HTTP server in the background. The metadata file may contain a single entity (<md:EntityDescriptor>) or multiple entities (<md:EntitiesDescriptor>). The latter is more common as well as more practical as you can manage metadata for multiple  Service Provider entities in a single file.

A typical use case involves a signed metadata aggregate (<md:EntitiesDescriptor>) published by a Federation. In this section, we show how to use a metadata provider of type FileBackedHTTPMetadataProvider to load the aggregate.

For illustration, let's assume that: (1) the top-level <md:EntitiesDescriptor> element of the XML document is signed; (2) the top-level <md:EntitiesDescriptor> element of the XML document is decorated with a validUntil attribute; (3) the validity interval is two weeks (P14D) in duration; and (4) the server supports HTTP conditional GET. The sample metadata provider shown below retrieves the metadata, verifies the signature, and checks the expiration date before loading the metadata into IdP memory:

<!--
    Load (and reload) a signed metadata aggregate from a remote HTTP server.

    This sample configuration assumes: (1) the top-level element of the XML 
    document is signed; (2) the top-level element of the XML document is 
    decorated with a validUntil attribute; (3) the validity interval is two 
    weeks (P14D) in duration; and (4) the server supports HTTP conditional GET.

    The metadata refresh process is influenced by the configured values of 
    the minRefreshDelay attribute (default: PT30S) and the maxRefreshDelay 
    attribute (default: PT4H) and also by any cacheDuration and validUntil 
    attributes in the metadata itself. If the server does not support HTTP 
    conditional GET, the attributes should be adjusted accordingly.
-->
<MetadataProvider id="RemoteMetadataAggregate" xsi:type="FileBackedHTTPMetadataProvider"
                  backingFile="%{idp.home}/metadata/federation-metadata-copy.xml"
                  metadataURL="http://example.org/metadata/federation-metadata.xml">

    <!--
        Verify the signature on the root element of the metadata aggregate 
        using a trusted metadata signing certificate.
    -->
    <MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
		certificateFile="%{idp.home}/conf/metadata/md-cert.pem"/>

    <!--
        Require a validUntil XML attribute on the root element and
        make sure its value is no more than 14 days into the future.
    -->
    <MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P14D"/>

    <!-- Consume all SP metadata in the aggregate -->
    <MetadataFilter xsi:type="EntityRoleWhiteList">
        <RetainedRole>md:SPSSODescriptor</RetainedRole>
    </MetadataFilter>       

</MetadataProvider>

See the FileBackedHTTPMetadataProvider topic for more information.

Metadata aggregates may be arbitrarily large. Although the FileBackedHTTPMetadataProvider loads metadata in the background, parsed metadata objects are stored in memory for efficiency. Therefore sufficient memory must be available to accommodate the entire aggregate. Obviously, a large aggregate will have significant memory requirements.  A more efficient approach leverages a DynamicHTTPMetadataProvider as discussed in the next section.

DynamicHTTPMetadataProvider

In contrast to FileBackedHTTPMetadataProvider, a DynamicHTTPMetadataProvider fetches entity metadata just-in-time from a remote HTTP server. Since the provider loads only the metadata that is actually needed, the space requirements of a DynamicHTTPMetadataProvider are optimal. OTOH, since dynamic metadata query occurs in-band, the SAML protocol exchange is blocked until metadata is successfully retrieved from the query server and processed by the IdP.

An instance of DynamicHTTPMetadataProvider essentially maps an entityID to a request URL based on a profile such as the SAML Profile for the Metadata Query Protocol, which itself is based on the more general Metadata Query Protocol specification. When queried, the server returns entity metadata (<md:EntityDescriptor>) for the entityID encoded in the request URL.

For illustration, let's assume that: (1) the top-level <md:EntityDescriptor> element of the XML document is signed; (2) the top-level <md:EntityDescriptor> element of the XML document is decorated with a validUntil attribute; (3) the validity interval is two weeks (P14D) in duration; and (4) the server conforms to the Metadata Query Protocol specification. The sample metadata provider shown below retrieves the metadata, verifies the signature, and checks the expiration date before loading the metadata into IdP memory:

<!--
    Load entity metadata from a remote HTTP server via the Metadata
    Query Protocol: https://github.com/iay/md-query

    The sample configuration below implicitly formulates a Metadata Query
    Protocol URL from the given base URL. For example, if the entityID is 
    https://sso.example.org/sp, the provider will request the following 
    resource: 

      https://mdq.example.org/global/entities/https%3A%2F%2Fsso.example.org%2Fsp

    The sample configuration below assumes: (1) the top-level element of 
    the XML document is signed; (2) the top-level element of the XML 
    document is decorated with a validUntil attribute; (3) the validity 
    interval is two weeks (P14D) in duration; and (4) the server conforms 
    to the Metadata Query Protocol specification.

    The metadata is cached for efficiency. The minCacheDuration attribute 
    (default: PT10M) and the maxCacheDuration attribute (default: PT8H) 
    strongly influence the life cycle of metadata in the local cache. (Any 
    cacheDuration and validUntil attributes in the metadata itself also 
    influence the behavior of the local cache.) The goal is to avoid needless 
    interaction with the HTTP server. To achieve this goal, you need to 
    understand the life cycle of the metadata on the server. For this reason, 
    it is best to ask your federation operator for specific recommendations.

    The HTTP Connection Attributes include the connectionRequestTimeout 
    attribute (default: PT5S), the connectionTimeout attribute (default: PT5S), 
    and the socketTimeout attribute (default: PT5S). The default values of these 
    attributes are overridden in the example below.
-->
<MetadataProvider id="DynamicEntityMetadata" xsi:type="DynamicHTTPMetadataProvider"
                  connectionRequestTimeout="PT2S"
                  connectionTimeout="PT2S"
                  socketTimeout="PT4S">
     <!--
        Verify the signature on the root element of the metadata 
        using a trusted metadata signing certificate.
    -->
    <MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
        certificateFile="%{idp.home}/credentials/mdq-cert.pem"/>
 
    <!--
        Require a validUntil XML attribute on the root element and
        make sure its value is no more than 14 days into the future.
    -->
    <MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P14D"/>
 
    <!-- Specify the base URL for the Metadata Query Protocol -->
    <MetadataQueryProtocol>https://mdq.example.org/global/</MetadataQueryProtocol>
 
</MetadataProvider>

See the DynamicHTTPMetadataProvider topic for more information.

Metadata-Driven Configuration

The goal of metadata-driven configuration is the ability to integrate with a new partner on the basis of metadata alone, preferably without touching the IdP configuration files.

The idea is to use entity attributes within the metadata to drive special relying party configurations. The use of entity attributes is the hallmark of a metadata-driven configuration.

The following table refers to some of the more common entity attributes. For more information, search the wiki on the @Name suffix shown in the table (which is also the corresponding Spring Java bean property name).

The following examples briefly illustrate the technique. See the MetadataDrivenConfiguration topic for numerous additional examples.

Entity Attributes and Local Metadata

Suppose you want to integrate with an SP that does not support the SHA-2 family of digest methods typically used by default with XML signature. To enable SHA-1 for that particular SP, add this entity attribute to its metadata:

<md:Extensions>
 <mdattr:EntityAttributes>
   <saml:Attribute Name="http://shibboleth.net/ns/profiles/securityConfiguration" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
     <saml:AttributeValue>shibboleth.SecurityConfiguration.SHA1</saml:AttributeValue>
   </saml:Attribute>
 </mdattr:EntityAttributes>
</md:Extensions>

Adding entity attributes to local metadata is straightforward since the IdP operator has complete control over the metadata. The next section shows how to add an entity attribute to remote metadata on-the-fly.

Entity Attributes and Remote Metadata

The following technique may be applied to any HTTP metadata provider (either a DynamicHTTPMetadataProvider or a FileBackedHTTPMetadataProvider).

Suppose SP metadata is published in a remote metadata source (such as Federation metadata). It may turn out that the SP does not fully support XML encryption despite the fact that its published metadata includes an encryption certificate (in which case you should of course notify the metadata producer, e.g. the Federation operator, and have them correct the metadata in question). To disable encryption for that particular SP, add the following child element to the relevant HTTP metadata provider:

<MetadataFilter xsi:type="EntityAttributes">
 <saml:Attribute Name="http://shibboleth.net/ns/profiles/encryptAssertions" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
   <saml:AttributeValue xsi:type="xsd:boolean">false</saml:AttributeValue>
 </saml:Attribute>
 <Entity>https://sp.example1.org</Entity>
 <Entity>https://sp.example2.org</Entity>
 <Entity>https://sp.example3.org</Entity>
</MetadataFilter>

The content of the <Entity> element is the entityID of the SP in question. Additional <Entity> elements may be specified, one for each SP from the parent metadata provider that does not support XML encryption.