ChainingMetadataProvider

The ChainingMetadataProvider is a container for an ordered sequence of metadata providers of any type. When searching for a particular entityID, the metadata resolver consults each child provider in the order in which it is listed. See the parent topic for a detailed description of the search ordering algorithm used by the metadata resolver.

Schema Names and location

The <MetadataProvider> element and the type ChainingMetadataProvider are defined by the urn:mace:shibboleth:2.0:metadata schema, which can be located at http://shibboleth.net/schema/idp/shibboleth-metadata.xsd.

Attributes

The following attributes are required on a metadata provider of type ChainingMetadataProvider:

Name	Type	Default	Description
`id`	String	required	Identifier for logging, identification for command line reload, etc.
`xsi:type`	String	required	Must be set to `"ChainingMetadataProvider"`

No other attributes are allowed.

Child Elements

A provider of type ChainingMetadataProvider may contain any number of child providers:

Name	Cardinality	Description
`<MetadataProvider>`	0 or more	An ordered sequence of metadata providers of any type (except the `ChainingMetadataProvider` type)

No other child elements are allowed.

Examples

Here is a brief summary of the examples in this section:

Example 1: A traditional configuration using FilesystemMetadataProvider for local metadata and FileBackedHTTPMetadataProvider for federation metadata
Example 2: A "no touch" configuration using LocalDynamicMetadataProvider for local metadata and FileBackedHTTPMetadataProvider for federation metadata
Example 3: A completely dynamic configuration using LocalDynamicMetadataProvider for local metadata and DynamicHTTPMetadataProvider for federation metadata
Example 4: A variation on the previous example that pre-fetches metadata for one or more high-value SPs

The following example illustrates one or more providers of type FilesystemMetadataProvider followed by a single FileBackedHTTPMetadataProvider:

Example 1: A traditional configuration

<MetadataProvider id="chain" xsi:type="ChainingMetadataProvider">
	<!-- 
		One or more providers of type FilesystemMetadataProvider for local metadata.
		Each metadata provider describes a static entity descriptor stored in a file.
	-->
	<MetadataProvider id="LocalMetadata" xsi:type="FilesystemMetadataProvider" ...>
      <!-- ... -->
	</MetadataProvider>
	
	<!-- 
		Exactly one provider of type FileBackedHTTPMetadataProvider for federation metadata.
		The metadata provider automatically refreshes a metadata aggregate (EntitiesDescriptor)
		which would otherwise expire.
	-->
	<MetadataProvider id="FederationMetadata" xsi:type="FileBackedHTTPMetadataProvider" ...>
      <!-- ... -->
	</MetadataProvider>
</MetadataProvider>

In the above example, local metadata is loaded before externally resolved federation metadata. This prevents federation metadata from accidentally overriding local metadata sources.

The following example is similar to the previous example except that multiple providers of type FilesystemMetadataProvider have been replaced with a single LocalDynamicMetadataProvider:

Example 2: A "no touch" configuration

<MetadataProvider id="chain" xsi:type="ChainingMetadataProvider">
	<!-- 
		Exactly one provider of type LocalDynamicMetadataProvider for local metadata.
		The metadata provider configures a source directory containing one or more
		static entity descriptors.
	-->
	<MetadataProvider id="LocalMetadata" xsi:type="LocalDynamicMetadataProvider" ...>
      <!-- ... -->
	</MetadataProvider>

	<!-- 
		Exactly one provider of type FileBackedHTTPMetadataProvider for federation metadata.
		The metadata provider automatically refreshes a metadata aggregate (EntitiesDescriptor)
		which would otherwise expire.
	-->
 <MetadataProvider id="FederationMetadata" xsi:type="FileBackedHTTPMetadataProvider" ...>

      <!-- ... -->
	</MetadataProvider>
</MetadataProvider>

In the above example, all local metadata is handled by a single LocalDynamicMetadataProvider. In this way, new local metadata may be added to the system without touching the configuration.

The following example is similar to the previous example except that the provider of type FileBackedHTTPMetadataProvider has been replaced with a DynamicHTTPMetadataProvider:

Example 3: A completely dynamic configuration

<MetadataProvider id="chain" xsi:type="ChainingMetadataProvider">
	<!-- 
		Exactly one provider of type LocalDynamicMetadataProvider for local metadata.
		The metadata provider configures a source directory containing one or more
		static entity descriptors.
	-->
	<MetadataProvider id="LocalMetadata" xsi:type="LocalDynamicMetadataProvider" ...>
      <!-- ... -->
	</MetadataProvider>
	
	<!-- 
		Exactly one provider of type DynamicHTTPMetadataProvider for federation metadata.
		Individual entity descriptors are fetched dynamically as needed from a metadata
		query server.
	-->
	<MetadataProvider id="FederationMetadata" xsi:type="DynamicHTTPMetadataProvider" ...>
      <!-- ... -->
	</MetadataProvider>
</MetadataProvider>

In the above example, federation metadata is sourced as needed (i.e., dynamically). This avoids having to load a large metadata aggregate.

Avoid redundant providers in the chain

Resolve federation metadata with either a FileBackedHTTPMetadataProvider (Example #2) or a DynamicHTTPMetadataProvider (Example #3) but not both. Assuming the same set of entities are represented in each case, the two approaches are mutually exclusive.

The following example expands on the previous example by adding one or more providers of type FileBackedHTTPMetadataProvider:

Example 4: A dynamic configuration with pre-fetch

<MetadataProvider id="chain" xsi:type="ChainingMetadataProvider">
	<!-- 
		Exactly one provider of type LocalDynamicMetadataProvider for local metadata.
		The metadata provider configures a source directory containing one or more
		static entity descriptors.
	-->
	<MetadataProvider id="LocalMetadata" xsi:type="LocalDynamicMetadataProvider" ...>
      <!-- ... -->
	</MetadataProvider>
	
	<!-- 
		One or more providers of type FileBackedHTTPMetadataProvider for federation
		metadata. Each provider loads (and reloads) a single entity descriptor
		(which would otherwise expire).
	-->
	<MetadataProvider id="HighValueEntityMetadata" xsi:type="FileBackedHTTPMetadataProvider" ...>
      <!-- ... -->
	</MetadataProvider>

	<!-- 
		Exactly one provider of type DynamicHTTPMetadataProvider for federation metadata.
		Individual entity descriptors are fetched dynamically as needed from a metadata
		query server.
	-->
	<MetadataProvider id="FederationMetadata" xsi:type="DynamicHTTPMetadataProvider" ...>
      <!-- ... -->
	</MetadataProvider>
</MetadataProvider>

In the above example, each FileBackedHTTPMetadataProvider loads (and reloads) the metadata of a single "high-value SP," that is, a known IdP partner. Note that the DynamicHTTPMetadataProvider is short-circuited for high-value SPs, which compensates for the risk associated with dynamic metadata query.