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 (MDQ, Dynamic, LocalDynamic) will be increasingly used instead.
Reference
Attributes
The type="XML" attribute must be present.
The following attributes are supported for all MetadataProvider types:
Name | Type | Req? | Default | Description |
|---|---|---|---|---|
type | string | Y | 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 | false | Whether 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:
Names | Type | Default | Description |
|---|---|---|---|
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 | boolean | false | If true, XML validation is performed when loading the resource |
reloadChanges | boolean | true | If 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 seconds | 0 | If 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:
| Name | Type | Default | Description |
|---|---|---|---|
discoveryFeed | boolean | true | When 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 seconds | 600 | Determines the minimum refresh interval when polling a remote resource for changes |
refreshDelayFactor | decimal between 0 and 1, non-inclusive | 0.75 | Factor 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 | boolean | true | 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 | boolean | false | When 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 |
|---|---|---|
any | Metadata filter plugins to run | |
<KeyInfoResolver> | 0 or 1 | Not generally used, it provides an extension point to override the low-level handling of |
In addition, the following element specific to this plugin type is supported:
| Name | Cardinality | Description |
|---|---|---|
| 0 or more | Specifies 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 | |
|---|---|---|---|
0 or 1 | Used to require the presence of a top-level signature over the entire resource and to control the verification process | ||
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 | ||
0 or more | Provides low-level control over the library used to remotely access the resource | ||
Examples
<MetadataProvider type="XML" path="/path/to/the/metadata.xml"/>
<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>