Page tree

The Shibboleth 2.x software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP30 and SP3 wiki spaces for current documentation on the supported versions.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 22 Next »

The <MetadataProvider> element configures a source of Metadata for the SP to use. Generally used only within the shibd service.

Unlike other configuration files which describe how the SP will behave, the metadata loaded by the SP describes the IdPs it wants to interact with. Each application determines the set of partner sites to trust by loading their metadata (or providing some kind of dynamic mechanism to do so).

For help with understanding and/or creating IdP metadata, see the Metadata and MetadataForIdP topics.

Common Attributes

  • type (string)
    • Name of plugin type.

XML MetadataProvider

Identified by type="XML", supplies metadata from local or remote XML files in the standard SAML 2.0 format.

The XML "portion" is a reloadable resource, which means that the XML content can be supplied inline, in a local file, or a remote file, and can be monitored for changes and reloaded on the fly. The root of the XML instance MUST be a <md:EntityDescriptor> or <md:EntitiesDescriptor> element.

<MetadataProvider type="XML" url="https://federation.org/metadata.xml" backingFilePath="fedmetadata.xml">
    <MetadataFilter type="Signature" certificate="fedsigner.pem"/>
</MetadataProvider>

Version 2.1 and Above: In the case of remotely acquired metadata, an instance that contains a cacheDuration attribute will affect the reload interval of the resource by potentially causing more frequent reloading.

Attributes

Inherits attributes supported by reloadable resources.

Version 2.4 and Above:

  • minRefreshDelay (time in seconds) (defaults to 600)
    • Determines the minimum refresh interval when polling a remote resource for changes.
  • maxRefreshDelay (time in seconds)
    • This is a synonym for the reloadInterval setting, and determines the maximum allowed refresh interval when polling a remote resource for changes.
  • refreshDelayFactor (decimal between 0 and 1, non-inclusive) (defaults to 0.75)
    • Factor applied to the metadata's own validity or caching period to determine the reload interval to use. Once applied, the result is bounded by the minRefreshDelay and maxRefreshDelay settings to determine the time of the next attempt. If reload attempts fail, the interval will increase in linear fashion to limit attempts.
  • discoveryFeed (boolean) (defaults to true)
    • When true, a JSON feed of IdP information will be produced and cached in memory for use by the new DiscoveryFeed handler. Can be disabled to save processing and memory.
  • legacyOrgNames (boolean, deprecated) {defaults to false)
    • When true, the JSON feed of IdP information (if produced) will use the same nonstandard sources for organization names as the Shibboleth centralized DS. This attribute is provided for transition purposes only, is deprecated and will be removed from future versions.

Child Elements

  • <MetadataFilter> (zero or more)
    • A filter to run against any metadata supplied by the plugin.

Dynamic MetadataProvider

Indicated by type="Dynamic", allows for resolution of metadata based on the "well-known" location mechanism defined in the SAML 2.0 metadata specification .

If an entityID is a URL, this plugin will attempt to lookup its metadata by resolving the URL into an XML instance rooted by a md:EntityDescriptor. The result will be cached for the length of time indicated by the metadata's cacheDuration or validUntil attributes (or until process restart or configuration reload).

Version 2.0:

Absolutely no trust processing is performed based on the location, use of TLS/SSL, or any other transport layer technology. The metadata is loaded as-is, and will be implicitly trusted. As a result, it is STRONGLY RECOMMENDED that this plugin be used only in conjunction with a Signature metadata filter to authenticate the source of the metadata.

Absent such a filtering step, the SP will essentially be insecure and open to straightforward attack.

Version 2.1 and Above:

As of version 2.1, this plugin includes support for authentication of the transport layer used to acquire the metadata. This allows for experimentation with the exchange of unsigned metadata using TLS-protected entityIDs, but the use of a Signature metadata filter is still permitted, in combination with or instead of the transport check.

Also as of version 2.1, the transport implementation is supplied by the same underlying code used for SOAP client communication, and the same configuration properties that affect that process are used, such as timeouts, client authentication via certificates or HTTP, etc.

Attributes

  • validate (boolean) (defaults to "false")
    • If "true", metadata will be schema validated when parsed.

Version 2.1 and Above:

  • maxCacheDuration (time in seconds) (defaults to 28800, 8 hours)
    • Upper bound on time before metadata for entity will be re-acquired.
  • verifyHost (boolean) (defaults to true)
    • If true, attempts to resolve metadata using a TLS-enabled URL will verify the hostname in the server's certificate against the expected hostname.
  • ignoreTransport (boolean) (defaults to false)
    • If true, authentication of the transport layer will be ignored when resolving metadata. This must be set to true to allow non-https entityID values. If false, a <TrustEngine> child element must be specified.

Version 2.4 and Above:

  • minCacheDuration (time in seconds) (defaults to 600)
    • Lower bound on time before metadata for entity will be re-acquired.
  • refreshDelayFactor (decimal between 0 and 1, non-inclusive) (defaults to 0.75)
    • Factor applied to the metadata's own validity or caching period to determine the reload interval to use. Once applied, the result is bounded by the minCacheDuration and maxCacheDuration settings to determine the time of the next attempt. If reload attempts fail, the existing metadata (if any) will be reused until it actually expires.

Child Elements

  • <MetadataFilter> (zero or more)
    • A filter to run against any metadata supplied by the plugin.

Version 2.1 and Above:

  • <TrustEngine> (optional)
    • A trust engine to apply to server certificates when resolving metadata using a TLS-enabled URL. This trust engine obviously must not require the use of metadata to operate. If not supplied, the ignoreTransport attribute must be set to true to avoid a configuration error. This is done to prevent a misconfigured trust engine from resulting in insecure metadata resolution.

Version 2.4 and Above

  • <Subst> (optional)
    • Simple transform whose element content consists of a string containing the substring "$entityID", into which the entityID value is substituted. If the element contains an encoded attribute set to "false", the value will be replaced directly, otherwise it will be URL-encoded.
  • <Regex> (optional)
    • Complex transform containing a match attribute containing a regular expression against which the entityID value is applied, and whose element content contains a replacement expression to run based on the results of the match. Only numeric/positional group references (e.g. $1) are supported.

Chaining MetadataProvider

Indicated by type="Chaining", allows multiple sources of metadata to be supplied in sequence.

While there is some limited capability for controlling the handling of duplicate entities, it is explicitly NOT supported for a single entityID to appear more than once with the same valid role, and the software will NOT behave predictably in such a case. In other words, if the same entity supports a given role, its metadata MUST be identical in all chained sources.

<MetadataProvider type="Chaining">
    <MetadataProvider type="XML" path="partners.xml"/>
    <MetadataProvider type="XML" url="https://federation.org/metadata.xml" backingFilePath="fedmetadata.xml"/>
</MetadataProvider>

Attributes

  • precedence ("first" or "last")
    • Controls the search process. If "last", then a search will examine every source of metadata and the last match found will be used. Otherwise a search will terminate at the first match found.

Child Elements

  • <MetadataProvider> (one or more)
    • The metadata sources to chain together.
  • No labels