Define a New Metadata Source

A great deal of functionality in the Shibboleth Identity Provider is driven from SAML metadata information. Metadata is provided to the IdP through Metadata Providers (yeah, we developers are pretty creative with our names). Metadata Providers are defined in the $IDP_HOME/conf/relying-party.xml file and are defined as follows.

For help with understanding and/or creating SP metadata, see the Metadata and MetadataForSP topics.

1 Define the Metadata Provider
2 Define a Metadata Filter (optional)
- 2.1 Chaining Metadata Filter
  - 2.1.1 Example Chaining Metadata Filter
- 2.2 Schema Validation Filter
  - 2.2.1 Example Schema Validation Filter
- 2.3 Required validUntil Filter
  - 2.3.1 Example Required validUntil Filter
- 2.4 Signature Validation Filter
  - 2.4.1 Example Signature Validation Filter
- 2.5 Entity Role WhiteList Filter
  - 2.5.1 Example Entity Role WhiteList Filter
3 Examples

Define the Metadata Provider

The IdP may have one, logical, Metadata Provider per relying partying group (though multiple, individual, Metadata Providers can be chained together to create the logical Provider used).

Metadata Providers are defined with a MetadataProvider element appearing after all the RelyingParty elements in the relying-party.xml file. Like other components the specific type of Metadata Provider is identified by the xsi:type attribute. Metadata Providers must also have an id attribute which assigns a unique id to the provider. This is used for debugging and logging purposes. The following types are supported.

The default IdP configuration uses a chaining metadata provider. You should define any new metadata providers within that chaining provider.

About Reloading Metadata Providers

As of version 2.2, all metadata providers which fetch metadata from an external (to the IdP software) source have undergone a change in when this fetching is performed. Prior to version 2.2 metadata was fetched during the first profile request that followed the cached metadata's expiration. If the metadata document was large this caused a very noticeable, but inexplicable, delay in the request processing. As of version 2.2 all metadata reloading occurs in the background and does not affect request processing (i.e. no more pauses due to metadata reloading).

The background process used to download metadata is designed to prevent problems where cached metadata expires but the remote source can not be reached. The algorithm used to determine the next refresh cycle uses three configurable inputs in addition to cacheDuration attributes that may be found in the metadata document itself. These inputs are: refreshDelayFactor, minRefreshDelay, and maxRefreshDelay. The later two are easy enough to understand. minRefreshDelay represents the smallest amount of time between cycles. maxRefreshDelay represents the largest amount of time between cycles.

The refreshDelayFactor is a bit harder to understand, but if you're familiar with how DHCP leases work you'll be familiar with the concept. The next refresh cycle for metadata is determined with the following algorithm:

Determine the earliest date/time of all (validUntil) and (now + cacheDuration) and (now + maxRefreshDelay)
If that time is before now, schedule a refresh in (now + minRefreshDelay). Stop.
Compute the difference between now and time determined in step one.
Multiply that number by the refreshDelayFactor to get the delay interval
Schedule the next refresh in now + computed delay interval

By using the delay factor in this way the IdP can get in a few refreshes (assuming reasonable values for the three configuration options) before a metadata document expires. This helps protect against problems that might arise if the remote metadata source is unavailable for short periods of time. It does not protect against metadata sources that are down for long periods of time.

Chaining Metadata Provider

This Metadata Provider provides a means of logically combining other Metadata Provider definitions. When the IdP requests metadata from this type of provider the provider returns the response of the first metadata provider, in the chain, that provides a response. For example, if providers A, B, and C are defined in a chain and both B and C contain an entity descriptor for urn:example.org:idp1, which the IdP is searching for, only the entity descriptor from B will be returned as it will be the first provider to return a non-empty response. No attempt to merge metadata from various metadata providers is made.

This provider is defined by the element <MetadataProvider xsi:type="ChainingMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"> with the following required attribute:

id - provides a unique, amongst metadata providers, identifier that may be used to reference the provider

Example File Backed HTTP Metadata Provider Configuration

<!-- RelyingParty elements above this point -->
<MetadataProvider xsi:type="ChainingMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" 
                  id="MyMetadata">

    <MetadataProvider xsi:type="FilesystemMetadataProvider"
                      id="InternalMetadata" 
                      metadataFile="/path/to/my/metadata-internal.xml" />

    <MetadataProvider xsi:type="FileBackedHTTPMetadataProvider"
                      id="External Metadata"
                      metadataURL="http://example.org/metadata.xml"
                      backingFile="/tmp/idp-metadata.xml" />

</MetadataProvider>

Filesystem Metadata Provider

The Filesystem Metadata Provider reads SAML 2 metadata from a file on the file system. Metadata is cached in memory for a period of time in order to improve performance. The metadata provider also monitors the file for changes and will reload the file upon detecting an update.

It is defined by the element <MetadataProvider xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"> with the following required attributes:

id - provides a unique, amongst metadata providers, identifier that may be used to reference the provider
metadataFile - the filesystem path to the metadata file

and the following optional attributes:

failFastInitialization (added in v2.2) - a boolean flag indicating whether, during startup, the IdP should fail to start if there is a problem fetching metadata (default value: true)
requireValidMetadata (added in v2.2) - a boolean flag that indicates that loaded metadata must be valid, according to the validUntil attributes found in the metadata (default value: true)
refreshDelayFactor (added in v2.2) - an number between 0.0 and 1.0, exclusive, used to determine the next metadata refresh cycle based on the current metadata's cache expiration time (default value: 0.75)
minRefreshDelay (added in v2.2) - a lower bound on the frequency of metadata refresh cycles given in XML duration notation (default value: PT5M)
maxRefreshDelay (added in v2.2) - an upper bound on the frequency of metadata refresh cycles given in XML duration notation (default value: PT4H)

Setting the min and max refresh delay to the same value is a nonsensical configuration. Don't do it.

Example Filesystem Metadata Provider Configuration

<!-- RelyingParty elements above this point -->
<MetadataProvider xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
                  id="MyMetadata"
                  metadataFile="/path/to/my/metadata.xml" />

File Backed HTTP Metadata Provider

The File Backed HTTP Metadata Provider works like the HTTP Metadata Provider, but stores metadata in a local temporary file upon successful retrieval. This protects against the case where metadata has been successfully fetched once but the remote server is offline during subsequent requests (even across IdP reboots). For users of Shibboleth 1.3 this Metadata Provider provides the same functionality as the common setup of a scheduled fetch via metadatatool and subsequent read for the metadata from the filesystem.

Note, as of version 2.2, this metadata provider supports deflate and gzip compression as well as conditional fetching of metadata based on Last-Modified and ETag headers.

It is defined by the element <MetadataProvider xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"> with the following required attributes:

id - provides a unique, amongst metadata providers, identifier that may be used to reference the provider
metadataURL - the URL of the metadata file
backingFile - the filesystem path where a backup copy of the metadata file is stored