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.
FileBackedHTTPMetadataProvider
The HTTPMetadataProvider type is deprecated
As of V3.4, the HTTPMetadataProvider type is deprecated and will be removed from IdP V4.0. Use a FileBackedHTTPMetadataProvider instead.
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. As of v3.3.0, 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.
Contents
- 1 Schema Names and location
- 2 Attributes
- 3 Child Elements
- 4 Examples
- 5 Frequently Asked Questions
- 5.1 What triggers the metadata refresh process?
- 5.2 What if the metadata resource is large?
- 5.3 What can I do to minimize the impact of metadata refresh?
- 5.4 What is HTTP conditional GET?
- 5.5 How do I customize the frequency of metadata refresh?
- 5.6 What is the backing file used for?
- 5.7 What happens if the provider is unable to load the backing file?
- 5.8 Does the provider support HTTP caching?
Schema Names and location
The <MetadataProvider> element and the type FileBackedHTTPMetadataProvider 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, the Reloading Attributes, or the HTTP Attributes may be configured. In addition, a FileBackedHTTPMetadataProvider has a few attributes of its own, some of which are required:
Name | Type | Default | Description |
|---|---|---|---|
| URL | required | The URL that the metadata is served from. |
| File specificaton | required | Specifies where the backing file is located. If the remote server is unavailable at startup, the backing file is loaded instead. |
| Boolean | true | Flag indicating whether initialization should first attempt to load metadata from the backup file. If true, foreground initialization will be performed by loading the backing file, and then a refresh from the remote HTTP server will be scheduled to execute in a background thread, after a configured delay. This can improve IdP startup times when the remote HTTP file is large in size. |
| Delay (ISO8601 format) |
| Delay duration after which to schedule next HTTP refresh when initialized from the backing file. |
Common Attributes
Reloading Attributes
HTTP Attributes
Configuring the HTTP Connection Attributes
For a FileBackedHTTPMetadataProvider, the HTTP Connection Attributes have the following default timeout values:
Name | Default |
|---|---|
|
|
|
|
|
|
Since the batch metadata refresh process runs in a background thread, a browser user will not notice such a delay.
Configuring the HTTP Caching Attributes
By default, a FileBackedHTTPMetadataProvider does not cache metadata (httpCaching="none"). Unless you've read the code or otherwise know what you're doing, do not override this setting.
Regardless of the value of the httpCaching attribute, a FileBackedHTTPMetadataProvider always issues HTTP conditional GET requests. For this reason, a custom HTTP client is seldom needed.
HTTP conditional GET is independent of caching strategy
Out of the box, a FileBackedHTTPMetadataProvider caches the response headers it needs to subsequently perform HTTP conditional GET but this caching-like behavior is not true HTTP caching. In particular, a FileBackedHTTPMetadataProvider does not cache the full HTTP response by default.
Child Elements
Any of the following child elements may be specified (in order).
Name | Cardinality | Description |
|---|---|---|
0 or more | A metadata filter applied to candidate metadata as it flows through the metadata pipeline | |
| 0 or 1 | A custom |
The former is common to all metadata providers while the latter is common to all HTTP metadata providers. The FileBackedHTTPMetadataProvider type has no child elements of its own.
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 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.