XMLMetadataProvider


Overview

Identified by type="XML", this MetadataProvider batch loads metadata from a single source. Remote metadata is almost always intended to be signed and should expire regularly in accordance with the TrustManagement model of the software, and use of the SignatureMetadataFilter and RequireValidUntilMetadataFilter is generally assumed.

This metadata plugin type is implemented as a reloadable XML resource, which means that the metadata can be supplied inline, in a local file, or a remote file, and can be monitored for changes and reloaded on the fly. The root of the XML in all cases MUST be either an <EntityDescriptor> or, more commonly with batches, <EntitiesDescriptor> element.

This is historically the most common way to configure metadata, but for large metadata sources the on-demand types (MDQDynamicLocalDynamic) will be increasingly used instead.

Reference

Attributes

The type="XML" attribute must be present.

The following attributes are supported for all MetadataProvider types:
NameTypeReq?DefaultDescription
type
stringY

Specifies the exact type of metadata plugin to use

id
string

A label for the metadata source, used in logging and status reporting
validate
boolean
falseWhether the XML should be schema validated before it is parsed. Note that some sources of metadata (e.g., ADFS) may contain a large number of extensions. The SP now includes a number of additional schemas to make validation of such extensions possible, but there are always exceptions.

It supports all of the attributes common to all reloadable configuration resources:


NamesTypeDefaultDescription
id
string
Identifies the component for logging purposes.
url
 URL

Remote location of an XML resource containing the required configuration. The SP does not verify the transport (i.e. it does not verify the X.509 certificate presented by the remote server when HTTPS is the transport).

path
local path

Path to a local file containing the required configuration

validate
booleanfalseIf true, XML validation is performed when loading the resource
reloadChanges
booleantrueIf a path attribute is used, the local file is monitored for changes and reloaded dynamically. This incurs some runtime overhead for locking, so should be disabled if not needed.
maxRefreshDelay
time in seconds0If a url attribute is used, this attribute sets the time between attempts to download a fresh copy of the resource. If 0 (the default), no reloading occurs. This incurs some runtime overhead for locking, so should be left at 0 if not needed
reloadInterval


Synonym for maxRefreshDelay

backingFilePath
local path
If a url attribute is used, the downloaded resource is copied to this location. If the software is started and the remote resource is unavailable or invalid, the backing file is loaded instead
certificate
local path
Path to a certificate containing a public key to use to require and verify an XML signature over the resource. The certificate's other content is ignored.
signerName
string
If present, the name is supplied to the <TrustEngine> used to verify an XML signature over the resource. A certificate containing the name must be available in the verification process (typically inside the signature).

In addition, the following attributes specific to this plugin type are supported:

NameTypeDefaultDescription
discoveryFeed
booleantrueWhen true, a JSON feed of IdP information will be produced and cached in memory for use by the DiscoveryFeed handler. Can be disabled to save processing and memory.
minRefreshDelay
time in seconds600

Determines the minimum refresh interval when polling a remote resource for changes

refreshDelayFactor
decimal between 0 and 1, non-inclusive0.75Factor applied to the metadata's own validity or caching period to determine the reload interval to use. Once applied, the result is bounded by the minRefreshDelay and maxRefreshDelay settings to determine the time of the next attempt. If reload attempts fail, the interval will increase in linear fashion to limit failed attempts.
dropDOM
booleantrue

When true, the underlying XML DOM structure is dropped after processing a new metadata instance. Set to false to maintain the DOM in memory if there are supplemental options being used that operate more efficiently with the DOM maintained.

tagsInFeed
booleanfalseWhen true, adds <EntityAttribute> extension attribute values (simple-valued only) to the discovery feed

Child Elements

The following child elements are supported across all MetadataProvider types:

Name

Cardinality

Description

<MetadataFilter>anyMetadata filter plugins to run
<KeyInfoResolver>0 or 1Not generally used, it provides an extension point to override the low-level handling of <ds:KeyInfo> elements and would be necessary to add support for some kind of custom XML key representation

In addition, the following element specific to this plugin type is supported:

NameCardinalityDescription

<DiscoveryFilter>

0 or moreSpecifies an inclusion or exclusion filter to apply to the entities in the metadata for purposes of the JSON discovery feed. Any entities excluded are still included in all other uses of the metadata.

These child elements are typically only used when relying on a remote configuration resource and are for advanced use cases.

Name

Cardinality

Description

<TrustEngine

0 or 1Used to require the presence of a top-level signature over the entire resource and to control the verification process

<CredentialResolver>

0 or 1

Used to require the presence of a top-level signature over the entire resource and to control the verification process.

Mutually exclusive with the <TrustEngine> element and the certificate attribute.

<TransportOption>

0 or moreProvides low-level control over the library used to remotely access the resource

Examples

Locally-Stored Metadata File
<MetadataProvider type="XML" path="/path/to/the/metadata.xml"/>
Remote Metadata Source
<MetadataProvider type="XML" url="http://metadata.example.com/md/TheMetadata.xml" backingFilePath="Metadata.xml.bck">
    <MetadataFilter type="Signature" certificate="metadata-signing-key.pem"/>
	<MetadataFilter type="RequireValidUntil" maxValidityInterval="8640000"/>
	<DiscoveryFilter type="Blacklist" matcher="EntityAttributes" trimTags="true"
      attributeName="http://macedir.org/entity-category"
      attributeNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
      attributeValue="http://refeds.org/category/hide-from-discovery" />
</MetadataProvider>