DynamicHTTPMetadataProvider

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

1 Overview
2 Reference
3 Examples
4 Frequently Asked Questions

Overview

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 configurable, with a simple way to configure support for the Metadata Query Protocol.

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.

As part of this “machinery”, the default HTTP client used with this provider is the “memory-caching” variant mentioned on the HttpClientConfiguration page, which automatically honors HTTP caching headers and caches results in memory. This mechanism operates independently of, and in addition to, all of the other caching behavior defined below, so bear this in mind when implementing your own metadata services for use with this provider. If you don’t want this behavior, simply define your own non-caching client to inject via the httpClientRef XML attribute.

Use this provider with remote metadata

The DynamicHTTPMetadataProvider is used with remote metadata. See the MetadataManagementBestPractices topic for more information.

Reference

Name	Type	Default	Description

Name	Type	Default	Description
maxConnectionsTotal	Integer	100	The maximum total number of simultaneous connections allowed by the HTTP client's connection pool manager. This attribute is incompatible with `httpClientRef`.
maxConnectionsPerRoute	Integer	100	The maximum number of simultaneous connections per route allowed by the HTTP client's connection pool manager. This attribute is incompatible with `httpClientRef`.
supportedContentTypes	Comma-delimited Strings	"application/samlmetadata+xml, application/xml, text/xml"	The MIME types supported by this provider when requesting metadata from the HTTP server. The `Content-Type` response header is validated against this list. This value cannot be specified as a bean property.

Name	Cardinality	Description

Name	Cardinality	Description
<TLSTrustEngine>	0 or 1	A custom TrustEngine used to evaluate TLS server certificates. This element conflicts with and is overridden by the httpClientSecurityParametersRef attribute. It contains a single <security:TrustEngine> element.
<MetadataQueryProtocol>	0 or 1	Constructs the metadata request URL based on the requirements of the Metadata Query Protocol
<Template>		Constructs the metadata request URL by means of a simple transform based on substitution
<Regex>		Constructs the metadata request URL by means of a complex transform based on a regular expression

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	Description

Name	Type	Description
transformRef	Bean ID	A reference to a transform function for the `entityID`. If used, the child element must be empty.

<Template> Child Element

If the <Template> child element is used, the metadata request URL is constructed by means of a simple transform. Specifically, the value of the entityID is substituted into the template parameter "${entityID}".

The <Template> child element has the following attributes:

Name	Type	Default	Description

Name

Type

Default

Description

encodingStyle

"none", "form", "path", or "fragment"

"form"

Determines whether and how the entityID value will be URL encoded prior to replacement. Allowed values are:

"none" : No encoding is performed.
"form" : Encoded using URL form parameter encoding (for query parameters).
"path" : Encoded using URL path encoding.
"fragment" : Encoded using URL fragment encoding.

The precise definition of these terms is defined in the documentation for the methods of the Guava library's UrlEscapers class.

transformRef

Bean ID

A reference to a transform function for the entityID. If used, the child element must be empty.

velocityEngine

Bean ID

shibboleth.VelocityEngine

Bean ID of a custom VelocityEngine to use, generally unneeded

<Regex> child element

If the <Regex> child element is used, the metadata request URL is constructed by means of a regular expression transform. The entityID value is first matched against the regular expression contained in the <Regex> element's match attribute. Then, the <Regex> element's content is treated as a replacement expression to run based on the results of the match.

The <Regex> child element has the following required attribute:

Name	Type	Req?