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.
DynamicHTTPMetadataProvider
The DynamicHTTPMetadataProvider fetches entity metadata just-in-time from a remote HTTP server. The metadata request URL is constructed by applying a transform to the entityID. The transform strategy is configured in a child element.
Metadata is cached in memory subject to a complex set of interacting settings and the cache indicators within the metadata itself, and also can be saved to disk and reloaded back into memory at reload or startup time to restore the state of the cache. This isn't a fully redundant safety net but can be used as part of an overall strategy to reduce the risk of relying on remote sources in real-time. Ultimately, remote sources have to be bulletproof or there will be outages. This can be mitigated but not fully eliminated as a risk.
Use this provider with remote metadata
The DynamicHTTPMetadataProvider is used with remote metadata. See the MetadataManagementBestPractices topic for more information.
Contents
- 1 Schema Names and location
- 2 Attributes
- 3 Child Elements
- 4 Examples
- 5 Frequently Asked Questions
- 5.1 What does “dynamic” mean?
- 5.2 How does metadata query work?
- 5.3 How long does the metadata remain in the IdP’s local cache?
- 5.4 Does the HTTP client cache the response in memory?
- 5.5 Does the HTTP client support HTTP conditional GET?
- 5.6 What if the metadata query server is down or unavailable?
- 5.7 What can I do to minimize the impact of metadata query?
Schema Names and location
The <MetadataProvider> element and the type DynamicHTTPMetadataProvider 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 Dynamic Attributes, or the HTTP Attributes may be configured.
Common Attributes
Dynamic Attributes
Configuring the Dynamic Attributes
Configure the Dynamic Attributes for the desired cache behavior. In particular, the minCacheDuration attribute and/or the maxCacheDuration attribute should be adjusted based on the life cycle of the metadata. Note that the cacheDuration attribute in metadata (if any) contributes to the overall cache behavior.
HTTP Attributes
The following HTTP attributes are exclusive to the DynamicHTTPMetadataProvider type:
Name | Type | Default | Description |
|---|---|---|---|
| Integer | 100 | The maximum total number of simultaneous connections allowed by the HTTP client's connection pool manager. This attribute is incompatible with |
| Integer | 100 | The maximum number of simultaneous connections per route allowed by the HTTP client's connection pool manager. This attribute is incompatible with |
| List of String (comma-separated) | "application/samlmetadata+xml, application/xml, text/xml" | The MIME types supported by this provider when requesting metadata from the HTTP server. The |
Configuring the HTTP Connection Attributes
For a DynamicHTTPMetadataProvider, the HTTP Connection Attributes have aggressive default timeout values:
Name | Default |
|---|---|
|
|
|
|
|
|
These may be tightened further if desired.
Configuring the HTTP Caching Attributes
By default, a DynamicHTTPMetadataProvider caches metadata in memory (httpCaching="memory"). The default values of the HTTP Caching Attributes are optimized for numerous, relatively small metadata files (i.e., single entity descriptors).
A file cache is volatile
A file cache will not survive a restart and so there is little (if any) benefit in overriding the default in-memory caching strategy.
Child Elements
Any of the following child elements may be specified, in the specified order (i.e. filters must appear first, then optionally a trust engine, and finally one of the request construction elements.
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 |
| 0 or 1 | Constructs the metadata request URL based on the requirements of the Metadata Query Protocol |
| 0 or 1 | Constructs the metadata request URL by means of a simple transform based on substitution |
| 0 or 1 | Constructs the metadata request URL by means of a complex transform based on a regular expression |
The <MetadataFilter> child element is common to all metadata providers while the <TLSTrustEngine> child element is common to all HTTP metadata providers. The remaining child elements are exclusive to the DynamicHTTPMetadataProvider type.
At most one of the <MetadataQueryProtocol>, <Template>, or <Regex> child elements is allowed. If none are configured, the provider constructs the metadata request URL directly from the entityID. This corresponds to the "well-known location" mechanism defined in the SAML 2.0 Metadata specification, section 4.1.
Don't forget to configure a child element
If you forget to configure a child element, the provider will default to the well-known location strategy. This constrains the entityID to be an URL (not an URN) but the provider does not check the URL scheme. If the scheme on the entityID is "http:", the metadata exchange will be vulnerable to a man-in-the-middle attack. For this reason, the well-known location strategy should be avoided in most cases.
<MetadataQueryProtocol> child element
If the <MetadataQueryProtocol> child element is used, the metadata request URL is constructed according to the SAML Profile for the Metadata Query Protocol, which itself is based on the Metadata Query Protocol specification. The content of the <MetadataQueryProtocol> child element will be used as the "Base URL" defined in that specification.
The <MetadataQueryProtocol> child element has the following optional attribute:
Name | Type | Default | Description |
|---|---|---|---|
| Bean ID | A reference to a transform function for the |