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.
type
(string)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.
Inherits attributes supported by reloadable resources.
Version 2.4 and Above:
minRefreshDelay
(time in seconds) (defaults to 600)maxRefreshDelay
(time in seconds)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)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)legacyOrgNames
(boolean, deprecated) (defaults to false)Version 2.5 and Above
dropDOM
(boolean) (defaults to true)tagsInFeed
(boolean) (defaults to false)<MetadataFilter>
(zero or more)Version 2.1 and Above:
<TransportOption>
(zero or more)Version 2.5 and Above
<DiscoveryFilter>
(zero or more)type
("Whitelist" or "Blacklist")matcher
(string)Example <MetadataProvider>
with <DiscoveryFilter>
that applies a blacklist to entities in the metadata for purposes of the JSON discovery feed optionally produced by the plugin. This blacklist is based on the presence of the http://refeds.org/category/hide-from-discovery entity attribute.
<MetadataProvider type="XML" uri="http://federation.org/federation-metadata.xml" backingFilePath="federation-metadata.xml" reloadInterval="7200"> <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/> <MetadataFilter type="Signature" certificate="fedsigner.pem"/> <DiscoveryFilter type="Blacklist" matcher="EntityAttributes" trimTags="true" attributeName="http://macedir.org/entity-category" attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" attributeValue="http://refeds.org/category/hide-from-discovery" /> </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.
validate
(boolean) (defaults to "false")Version 2.1 and Above:
maxCacheDuration
(time in seconds) (defaults to 28800, 8 hours)verifyHost
(boolean) (defaults to true)ignoreTransport
(boolean) (defaults to false)<TrustEngine>
child element must be specified.Version 2.4 and Above:
minCacheDuration
(time in seconds) (defaults to 600)refreshDelayFactor
(decimal between 0 and 1, non-inclusive) (defaults to 0.75)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.Version 2.6 and Above:
cleanupInterval
(time in seconds) (defaults to 1800)cleanupTimeout
(time in seconds) (defaults to 1800)<MetadataFilter>
(zero or more)Version 2.1 and Above:
<TrustEngine>
(optional)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)encoded
attribute set to "false", the value will be replaced directly, otherwise it will be URL-encoded.<Regex>
(optional)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.Indicated by type="Chaining"
, allows multiple sources of metadata to be supplied in sequence.
With V2.4 and above, this is implied by any configuration with multiple <MetadataProvider>
elements, so is no longer explicitly needed unless one of its optional settings is required.
While there is some limited capability for controlling the handling of duplicate entities, it is explicitly NOT supported for a single |
<MetadataProvider type="Chaining"> <MetadataProvider type="XML" path="partners.xml"/> <MetadataProvider type="XML" url="https://federation.org/metadata.xml" backingFilePath="fedmetadata.xml"/> </MetadataProvider> |
precedence
("first" or "last")<MetadataProvider>
(one or more)Indicated by type="Folder"
, loads a single directory of local file-based metadata sources as though each individual file were defined via the type="XML"
provider inside a chain. Each ordinary file found in the specified directory is loaded, but nested directories are ignored. The directory is not monitored for changes, so additional files added after initial configuration will not be seen, but changes to the existing files found can be detected in the usual fashion.
<MetadataProvider type="Folder" path="metadata"/> |
path
(absolute or relative pathname)precedence
("first" or "last")reloadChanges
(boolean) (defaults to "true")validate
(boolean) (defaults to "false")discoveryFeed
(boolean) (defaults to true)legacyOrgNames
(boolean, deprecated) (defaults to false)dropDOM
(boolean) (defaults to true)Any child elements supported by the type="XML"
plugin documented above can be included, and will be applied uniformly to all embedded sources.