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
| Table of Contents |
|---|
In a typical A typical use case is to load (and default) configuration, only one resource is configured for metadata configuration, a file called metadata-providers.xml containing a "root" <MetadataProvider> element. This could make use of a single resource such as a periodically reload) entity metadata from a local file:
...
| Include Page |
|---|
...
It could also point to a third-party-provided metadata source, usually referred to as a "federation", with filters to verify the signature on the XML document using a pre-established public key:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<MetadataProvider id="FederationMetadata" xsi:type="FileBackedHTTPMetadataProvider"
xmlns="urn:mace:shibboleth:2.0:metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:mace:shibboleth:2.0:metadata http://shibboleth.net/schema/idp/shibboleth-metadata.xsd"
metadataURL="http://federation.example.org/metadata.xml"
backingFile="%{idp.home}/metadata/federation-metadata.xml">
<MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
certificateFile="%{idp.home}/conf/metadata/fed-signing-key.pem"/>
<MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P14D"/>
</MetadataProvider> |
One can combine the two approaches inside a ChainingMetadataProvider, which combines two or more sources.
|
...
<MetadataProvider id="LocalMetadata" xsi:type="FilesystemMetadataProvider"
xmlns="urn:mace:shibboleth:2.0:metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:mace:shibboleth:2.0:metadata http://shibboleth.net/schema/idp/shibboleth-metadata.xsd"
failFastInitialization="true"
metadataFile="%{idp.home}/metadata/my-metadata.xml"/>
|
Another use case is to load (and periodically reload) a metadata aggregate from a remote source via HTTP:
| Include Page | ||||
|---|---|---|---|---|
|
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
...
| xsi:type | Function |
|---|---|
| A container for an ordered sequence of metadata providers of any type | |
| A dynamic provider that fetches metadata just-in-time from a suitably configured HTTP server | |
| LocalDynamicMetadataProvider | A dynamic provider that fetches metadata just-in-time from a local source such as a filesystem directory |
| A reloading provider that loads (and reloads) a metadata file from the filesystem in a background thread | |
| A reloading provider that loads (and reloads) a metadata file from an HTTP server in a background thread | |
| HTTPMetadataProvider | DEPRECATED: Use FileBackedHTTPMetadataProvider instead. |
| A reloading provider that loads (and reloads) a metadata file from a more complex source (such as SVN) in a background thread | |
A provider that allows metadata to be specified inline |
...
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
The following attributes are required on all metadata provider types:
...
The following attributes are available on all metadata provider types (except the ChainingMetadataProvider type):
...
requireValidMetadata
...
Whether candidate metadata found by the resolver must be valid in order to be returned (where validity is implementation specific, but in SAML cases generally depends on a validUntil attribute.) If this flag is true, then invalid candidate metadata will not be returned.
...
failFastInitialization
...
| Include Page | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
The following attributes are only supported on the reloading "batch-oriented" metadata providers (ResourceBackedMetadataProvider, FilesystemMetadataProvider, and FileBackedHTTPMetadataProvider):
...
Identifies an optional Set<MetadataIndex> used to support resolution of metadata based on criteria other than an entityID.
...
Flag indicating whether resolution may be performed solely by applying predicates to the entire metadata collection, when an entityID input criterion is not supplied.
...
| Include Page | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
The following attributes are only supported on the dynamic metadata providers (DynamicHTTPMetadataProvider and LocalDynamicMetadataProvider):
...
The maximum duration for which metadata will be allowed to be idle (no requests for it) before it is removed from the cache.
...
The interval at which the internal cleanup task should run. This task performs background maintenance tasks, such as the removal of expired and idle metadata.
...
The directory used for an internally-constructed filesystem-based persistent cache. This is a convenience parameter to avoid specifying a full bean via persistentCacheManagerRef. This option will be ignored if persistentCacheManagerRef is specified.
...
The delay after which to schedule the background initialization from the persistent cache when initializeFromPersistentCacheInBackground=true.
...
Identifies a Spring bean for an optional Predicate which determines whether a given entity should be loaded from the persistent cache at resolver initialization time.
| Include Page | ||||
|---|---|---|---|---|
|
Anchor HTTPAttributes HTTPAttributes
HTTP Attributes
| HTTPAttributes | |
| HTTPAttributes |
The attributes in this section (and the following subsections) are only supported on the HTTP metadata providers (DynamicHTTPMetadataProvider and FileBackedHTTPMetadataProvider).
An HTTP metadata provider includes a default implementation of the org.apache.http.client.HttpClient interface. The attributes in the following subsections control the behavior of the default HTTP client. To override the default client implementation, configure the following attribute:
...
A reference to an externally defined Spring bean that specifies an org.apache.http.client.HttpClient object. This attribute conflicts with and overrides all of the HTTP attributes. See the HttpClientConfiguration topic for more information.
Use of the httpClientRef attribute precludes the use of any and all of the HTTP attributes in the following subsections.
...
The following attributes apply to the HTTP connections obtained and managed by an HTTP metadata provider:
...
DEPRECATED: Use connectionTimeout instead.
...
The following security-related attributes apply to any HTTP metadata provider:
...
If true, no TLS certificate checking will take place over an HTTPS connection. This attribute is incompatible with httpClientRef. (Be careful with this setting, it is typically only used during testing. See the HttpClientConfiguration topic for more information.)
...
DEPRECATED: Use httpClientSecurityParametersRef instead.
...
DEPRECATED: Use httpClientSecurityParametersRef instead.
...
The following attributes configure an HTTP proxy for use with an HTTP metadata provider:
...
The hostname of the HTTP proxy through which connections will be made. This attribute is incompatible with httpClientRef.
...
The port of the HTTP proxy through which connections will be made. This attribute is incompatible with httpClientRef.
...
The username used with the HTTP proxy through which connections will be made. This attribute is incompatible with httpClientRef.
...
The password used with the HTTP proxy through which connections will be made. This attribute is incompatible with httpClientRef.
...
The following attributes configure an HTTP cache on an HTTP metadata provider:
...
The type of HTTP caching to perform. There are three choices:
“none”indicates the HTTP response is not cached"file”indicates the HTTP response is written to disk (but will not survive a restart)"memory"indicates the HTTP response is stored in memory
This attribute is incompatible with httpClientRef and its value may not be specified as a bean property.
...
If httpCaching="file", this attribute specifies where retrieved files are to be cached. This attribute is incompatible with httpClientRef.
...
"memory": 50
"file": 100
...
The maximum number of responses written to cache. This attribute is incompatible with httpClientRef.
...
"memory": 1048576 (1MB)
"file": 10485760 (10MB)
...
The maximum response body size that may be cached, in bytes. This attribute is incompatible with httpClientRef.
...
| Include Page | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
...
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.
Anchor SearchOrdering SearchOrdering
Search Ordering
| SearchOrdering | |
| SearchOrdering |
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:
- Metadata sources combined via a chain are searched in the order in which they occur in the chain, and the first entry matching the entityID is returned.
If multiple "top level" Metadata Providers are provided then they are searched in an order derived from the (numeric) value of the
sortKeyattribute (lowest key first). If nosortKeyis specified, then the search order is undefined.- In whatever order of sources is in effect, the first entry matching the entityID is returned.
- If a single metadata source contains multiple entries with the same entityID, then which entry is returned is undefined (exception: invalid entries would be ignored in favor of valid ones in most cases).
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 cannot be are not used for metadata verification (despite the confusing names):
ChainingMetadataExplicitKeyMetadataPKIXX509CredentialMetadataExplicitKeySignatureMetadataPKIXSignatureStaticPKIXX509Credential
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.
| Note | ||
|---|---|---|
| ||
| 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.
When configuring more than one MetadataFilter, you need not wrap them in a "ChainingFilter" filter.
The SignatureValidation filter 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, or a a PEM-format public key may be supplied inline via the <PublicKey> element. For more advanced requirements, an inline <security:TrustEngine> element. may be defined element.
| Note | ||
|---|---|---|
| ||
As a child element of the
element should be declared inside a |