FilesystemMetadataProvider

Namespace: urn:mace:shibboleth:2.0:metadata
Schema: http://shibboleth.net/schema/idp/shibboleth-metadata.xsd

Overview

The FilesystemMetadataProvider loads metadata from a file on the local file system. The provider will periodically reload the metadata if the file changes.

Use this provider with local metadata

The FilesystemMetadataProvider is used with local metadata. See the MetadataManagementBestPractices topic for more information.

Reference

Specific XML Attributes

Name	Type	Req?	Description
`metadataFile`	String	Y	The absolute path to the local metadata file to be loaded

Common XML Attributes

Name	Type	Default	Description
The following attributes are required on all metadata provider types:
id	String		Identifier for logging, identification for command line reload, etc.
xsi:type	String		Specifies the exact type of provider to use (from those listed above, or a custom extension type)
The following attributes are common to all metadata provider types except the `ChainingMetadataProvider` type:
requireValidMetadata	Boolean	true	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	Boolean	true	Whether to fail initialization of the underlying MetadataResolverService (and possibly the IdP as a whole) if the initialization of a metadata provider fails. When false, the IdP may start, and will continue to attempt to reload valid metadata if configured to do so, but operations that require valid metadata will fail until it does.
sortKey	Integer		Defines the order in which metadata providers are searched (see below), can only be specified on top level `<MetadataProvider>` elements.
metricsBaseName	String		Overrides the default name of the metrics reported out by various metadata providers.
The following are advanced settings supporting a new low-level feature allowing metadata lookup by keys other than the unique entityID and are rarely of use to a deployer.
criterionPredicateRegistryRef	Bean ID		Identifies the a custom CriterionPredicateRegistry bean used in resolving predicates from non-predicate input criteria
useDefaultPredicateRegistry	Boolean	true	Flag which determines whether the default CriterionPredicateRegistry will be used if a custom one is not supplied explicitly
satisfyAnyPredicates	Boolean	false	Flag which determines whether predicates used in filtering are connected by a logical 'OR' (true) or by logical 'AND' (false)

Reloading XML Attributes

The following attributes are common to all reloading "batch-oriented" metadata providers (i.e., FileBackedHTTPMetadataProvider, FilesystemMetadataProvider, and ResourceBackedMetadataProvider):

Name	Type	Default	Description
minRefreshDelay	Duration	PT30S	Lower bound on the next refresh from the time calculated based on the metadata's expiration
maxRefreshDelay	Duration	PT4H	Upper bound on the next refresh from the time calculated based on the metadata's expiration
refreshDelayFactor	Real Number (strictly between 0.0 and 1.0)	0.75	A factor applied to the initially determined refresh time in order to determine the next refresh time (typically to ensure refresh takes place prior to the metadata's expiration). Attempts to refresh metadata will generally begin around the product of this number and the maximum refresh delay.
expirationWarningThreshold	Duration	PT0S (disabled)	For each attempted metadata refresh (whether or not fresh metadata is obtained), if `requireValidMetadata` is true, and there is a `validUntil` XML attribute on the document root element, and the difference between `validUntil` and the current time is less than `expirationWarningThreshold`, the system logs a warning about the impending expiration.
indexesRef	Bean ID		Bean ID of a Set<MetadataIndex> used to support resolution of metadata based on criteria other than an entityID, e.g. resolving by protocol endpoint for CAS or by SAML Artifact source ID.
resolveViaPredicatesOnly	Boolean	false	Flag indicating whether resolution may be performed solely by applying predicates to the entire metadata collection, when an entityID input criterion is not supplied
parserPoolRef	Bean ID	shibboleth.ParserPool	Identifies a Spring bean for the XML parser used to parse metadata. Generally should not be changed.
taskTimerRef	Bean ID		Identifies a Spring bean containing a Java Timer used to schedule reloads. When not set, an internal one is created. Generally should not be changed.

Common XML Elements

The following child element is common to all MetadataProvider types except the ChainingMetadataProvider type:

0 or more

A metadata filter applied to candidate metadata as it flows through the metadata pipeline

Examples

The following example loads a metadata file from the file system:

Load entity metadata from a file

<!--
    Load (and reload) entity metadata from a local file.

    The metadata refresh process is determined by the configured values of the 
    minRefreshDelay attribute (default: PT30S) and maxRefreshDelay attribute 
    (default: PT4H). If you want to load (or reload) the metadata immediately, 
    restart the IdP.
-->
<MetadataProvider id="LocalEntityMetadata" xsi:type="FilesystemMetadataProvider"
                  metadataFile="%{idp.home}/metadata/local-metadata.xml"/>