The Shibboleth IdP V3 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP4 wiki space for current documentation on the supported version.

FilesystemMetadataProvider

The FilesystemMetadataProvider loads metadata from a file on the local file system. The provider can be configured to periodically reload the metadata if needed.

Use this provider with local metadata

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

Contents

Schema Names and location

The <MetadataProvider> element and the type FilesystemMetadataProvider are defined by the urn:mace:shibboleth:2.0:metadata schema, which can be located at http://shibboleth.net/schema/idp/shibboleth-metadata.xsd.

Attributes

Any of the Common Attributes or the Reloading Attributes may be configured. In addition one attribute metadataFile must be specified:

NameTypeDefaultDescription
metadataFile
StringrequiredThe absolute path to the local metadata file to be loaded

Common Attributes

The following attributes are required on all metadata provider types:

NameTypeDefaultDescription
idStringrequiredIdentifier for logging, identification for command line reload, etc.
xsi:typeStringrequiredSpecifies 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:

NameTypeDefaultDescription

requireValidMetadata

Booleantrue

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          

BooleantrueWhether 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.
sortKeyInteger
Defines the order in which metadata providers are searched (see below), can only be specified on top level <MetadataProvider> elements.
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 3.3Bean ID
Identifies the a custom CriterionPredicateRegistry bean used in resolving predicates from non-predicate input criteria.
useDefaultPredicateRegistry 3.3BooleantrueFlag which determines whether the default CriterionPredicateRegistry will be used if a custom one is not supplied explicitly.
satisfyAnyPredicates 3.3BooleanfalseFlag which determines whether predicates used in filtering are connected by a logical 'OR' (true) or by logical 'AND' (false).

Reloading Attributes

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

NameTypeDefaultDescription
parserPoolRef                 Bean IDshibboleth.ParserPoolIdentifies a Spring bean for the XML parser used to parse metadata. Generally should not be changed.
taskTimerRefBean ID
Identifies a Spring bean containing a Java TaskTimer used to schedule reloads. When not set, an internal timer is created. Generally should not be changed.
minRefreshDelayDurationPT30SLower bound on the next refresh from the time calculated based on the metadata's expiration.
maxRefreshDelayDurationPT4HUpper bound on the next refresh from the time calculated based on the metadata's expiration.
refreshDelayFactorReal Number (strictly between 0.0 and 1.0)0.75A 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.
indexesRef 3.3Bean ID

Identifies an optional Set<MetadataIndex> used to support resolution of metadata based on criteria other than an entityID.

resolveViaPredicatesOnly 3.3Booleanfalse

Flag indicating whether resolution may be performed solely by applying predicates to the entire metadata collection, when an entityID input criterion is not supplied.

expirationWarningThreshold 3.4DurationPT0S (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.

Child Elements

Any of the following child elements may be specified (in order).

NameCardinalityDescription
<MetadataFilter>0 or moreA metadata filter applied to candidate metadata as it flows through the metadata pipeline

The <MetadataFilter> child element is common to all metadata providers. The FilesystemMetadataProvider type has no child elements of its own.

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"/>