FileBackedHTTPMetadataProvider
Namespace: urn:mace:shibboleth:2.0:metadata
Schema: http://shibboleth.net/schema/idp/shibboleth-metadata.xsd
Overview
The FileBackedHTTPMetadataProvider
loads a metadata file from an HTTP server. The provider periodically reloads the metadata file if necessary.
Use this provider with remote metadata
The FileBackedHTTPMetadataProvider
is used with remote metadata. See the MetadataManagementBestPractices topic for more information.
The FileBackedHTTPMetadataProvider
spools the metadata contents to a local backing file, which is used at startup. Note that the backing file is only used at startup. A refresh operation never consults the backing file since the latter can't possibly represent newer metadata than what is already cached in memory.
Reference
Examples
A typical use of FileBackedHTTPMetadataProvider
is to load (and periodically reload) a metadata aggregate from a remote source via HTTP:
Note that the metadata is loaded (and reloaded) out-of-band and therefore will not interfere with any SAML protocol exchange.
Frequently Asked Questions
See also Troubleshooting.
What triggers the metadata refresh process?
A FileBackedHTTPMetadataProvider
loads (and reloads) metadata in the background, independent of normal IdP operation. The frequency of metadata refresh is influenced by the Reloading Attributes. In particular, the minRefreshDelay
and maxRefreshDelay
attributes strongly influence the frequency of metadata refresh. Any cacheDuration
and validUntil
attributes in the metadata itself also influence the process.
What if the metadata resource is large?
Large metadata files consume a significant amount of memory, especially during the reload process (when the IdP must have both the old and the new metadata at hand). Precise memory requirements depend on overall IdP load and other deployment-specific factors but large metadata files (such as those distributed by some federations) may require a system configured with 2GB of memory or even more. Ask your federation operator for specific recommendations.
Although metadata refresh can put significant load on the system, all refresh operations are performed in the background, independent of normal IdP operation. Assuming there are no resource limiting factors (such as inadequate memory), end users will not notice the effects of metadata refresh.
What can I do to minimize the impact of metadata refresh?
There are at least two things you can do to help minimize the impact of the metadata refresh process: 1) install and configure adequate memory on your system, and 2) customize the frequency of metadata refresh for optimal performance. In any case, the FileBackedHTTPMetadataProvider
implementation has two features that positively affect metadata refresh: background processing and HTTP conditional GET. Neither of these features is configurable, however, so there is nothing further you need to do beyond the two items mentioned above.
What is HTTP conditional GET?
A conforming server will respond to an HTTP conditional GET request (RFC 7232) with a 304 (Not Modified) status code if the target resource has not changed since the last time it was requested. Note that a 304 response does not include a response body, which is more efficient than the corresponding 200 response (especially for large metadata files). More importantly, due to the manner in which the FileBackedHTTPMetadataProvider
is implemented, the IdP can safely ignore a 304 response, which precludes the need to redundantly process the metadata. For large signed metadata files, the savings can be quite significant.
How do I customize the frequency of metadata refresh?
To influence the frequency of metadata refresh, configure the following attributes on a FileBackedHTTPMetadataProvider
instance: minRefreshDelay
, maxRefreshDelay
, and refreshDelayFactor
. Optimal values for these attributes depend on 1) whether or not the server supports HTTP conditional GET, 2) the life cycle of metadata published on the server, and possibly other factors. Ask the metadata publisher for recommended best practices with respect to published metadata.
What is the backing file used for?
The backing file is only used at startup. If the remote server is unavailable at startup, the backing file is loaded instead and all the configured filters are run on the backing file. If a single filter fails, the backing file is not loaded. For example, if the provider contains a SignatureValidationFilter but the signature on the backing file can not be verified, the entire load operation fails.
What happens if the provider is unable to load the backing file?
If a FileBackedHTTPMetadataProvider
is unable to load the backing file at startup, and the failFastInitialization
attribute on the provider is set to true (the default), the metadata initialization process will halt. Additionally, if the idp.service.metadata.failFast property is set to true (not the default), the IdP as a whole will fail to initialize.
Does the provider support HTTP caching?
Yes, it does so internally, though not across restarts of the system (it will not have a cache tag at startup but will maintain one in memory after the initial request for metadata and do conditional GETs until the next restart).