The Shibboleth IdP generally requires SAML metadata to provision connectivity with relying parties and inform it about their capabilities and technical specifics. While you have the option to operate in a more "promiscuous" way (by enabling profiles for "unverified" RPs), this is relatively rare. In most cases, you will configure metadata sources in order to use the IdP's SAML features; this is done by adding <MetadataProvider> elements inside the metadata-providers.xml file.

Contents

A typical use case is to load (and periodically reload) entity metadata from a local file:

Another use case is to load (and periodically reload) a metadata aggregate from a remote source via HTTP:

Increasingly, the dynamic providers (LocalDynamicMetadataProvider and DynamicHTTPMetadataProvider) are used in lieu of the reloading providers (FilesystemMetadataProvider and FileBackedHTTPMetadataProvider). See the MetadataManagementBestPractices topic for use cases and recommendations.

The ChainingMetadataProvider is often used to combine two or more metadata sources. The metadata-providers.xml file that ships with the software declares such a chain "wrapper" by default.

Schema names and locations

Nearly all elements described in this page and its children are defined in the urn:mace:shibboleth:2.0:metadata namespace, the schema for which can be located at http://shibboleth.net/schema/idp/shibboleth-metadata.xsd. Throughout this document and its children, this is assumed to be the default XML namespace in effect. The namespace prefix "metadata:" is conventionally also bound to this namespace.

The namespace prefix "security:" is used to refer to the urn:mace:shibboleth:2.0:security namespace, the schema for which can be located at http://shibboleth.net/schema/idp/shibboleth-security.xsd, and is generally used only in advanced scenarios or for compatibility.

The namespace prefix "resource:"  is used to refer to the urn:mace:shibboleth:2.0:resource namespace, the schema for which can be located at http://shibboleth.net/schema/idp/shibboleth-resource.xsd. It is only used by the ResourceBackedMetadataProvider

The namespace prefix "samlmd:" is used to refer to the urn:oasis:names:tc:SAML:2.0:metadata namespace, the schema for which can be located at http://docs.oasis-open.org/security/saml/v2.0/saml-schema-metadata-2.0.xsd

MetadataProvider Types

The precise behavior of any <MetadataProvider> element is controlled by the xsi:type attribute (see below). The following types are supported and examples are provided for each type. If the urn:mace:shibboleth:2.0:metadata namespace is not the default, then a prefix (presumably "metadata:") is required when specifying these types.

xsi:typeFunction

ChainingMetadataProvider

A container for an ordered sequence of metadata providers of any type

DynamicHTTPMetadataProvider

A dynamic provider that fetches metadata just-in-time from a suitably configured HTTP server
LocalDynamicMetadataProviderA dynamic provider that fetches metadata just-in-time from a local source such as a filesystem directory

FilesystemMetadataProvider

A reloading provider that loads (and reloads) a metadata file from the filesystem in a background thread

FileBackedHTTPMetadataProvider

A reloading provider that loads (and reloads) a metadata file from an HTTP server in a background thread
HTTPMetadataProviderDEPRECATED: Use FileBackedHTTPMetadataProvider instead.

ResourceBackedMetadataProvider

A reloading provider that loads (and reloads) a metadata file from a more complex source (such as SVN) in a background thread

InlineMetadataProvider

A provider that allows metadata to be specified inline

Attributes

Configuration attributes common to two or more metadata providers are listed in the subsections below. Other attributes are specific to the xsi:type, and these are documented on the pages specific to each type.

Common Attributes

Reloading Attributes

Dynamic Attributes

HTTP Attributes

Child Elements

The following child elements may be used with all metadata provider types (except the ChainingMetadataProvider type):

NameCardinalityDescription
<MetadataFilter>0 or moreA metadata filter applied to candidate metadata as it flows through the metadata pipeline
<security:TrustEngine>0 or moreDEPRECATED: See the note at the bottom of this page

Other allowable child elements are specific to the xsi:type of the provider used, and these are documented on the pages specific to each type.

Miscellany

Multiple Configuration Files

As described in the ReloadableServices documentation, the configuration is actually loaded from a bean whose name is specified by the property idp.service.metadata.resources, with the default value shibboleth.MetadataResolverResources which in turn is defined in services.xml to be a list with one entry: the file metadata-providers.xml

You can, if you choose, override this with additional or different files or more advanced sources. Each resource must supply a "top level" <MetadataProvider> element with attributes and child elements as described above. Search order amongst multiple top level elements is arbitrated by the sortKey attribute, where lower values are processed before higher ones.

Search Ordering

If a specific relying party (as identified by a specific entityID) is duplicated in the metadata sources provided, then which precise entry is chosen is governed by the following rules:

V2 Compatibility

A single <MetadataProvider> element may be embedded in a legacy relying-party.xml file as described in the older documentation. Consult the V2 documentation for this, and do not mix and match this approach with newer configuration features.

During the V2 to V3 upgrade process, the original V2 relying-party.xml file is copied to metadata-providers.xml, to serve as the metadata configuration for the new version. It's strongly advisable after upgrading to update that file by stripping it of the older content and promote the <MetadataProvider> element in it to the root of the file. In the interim all other content in the file except for <MetadataProvider> elements (and any referenced <security:TrustEngine> elements) is ignored.

The following non-relevant trust engine types often found in a legacy relying-party.xml file are ignored if seen, and are not used for metadata verification (despite the confusing names):

New Capabilities in V3

The V3 metadata configuration syntax is backward-compatible with the V2 <MetadataProvider> syntax and adds some useful new shortcuts as well.

In anticipation of V4, a number of IdP features have been deprecated in V3. To ensure a seamless upgrade to V4, avoid the use of deprecated features in your V3 deployment. In particular, avoid any metadata-related features deprecated in V3.

You can now provide multiple metadata configuration files (not just multiple metadata sources in one file), as described above.

A SignatureValidation filter need not contain a trustEngineRef attribute referencing a separately-defined trust engine; instead a certificate file may be specified directly with the certificateFile attribute. Alternatively, a PEM-format public key may be supplied inline via the <PublicKey> element.

As a child element of the <MetadataProvider> element, the use of the <security:TrustEngine> element is DEPRECATED. If used at all, the element should be declared inside a SignatureValidation filter or in most cases simply replaced with the certificateFile attribute. See the SignatureValidationFilter topic for more information.