The Shibboleth IdP generally requires SAML metadata to provision connectivity with relying parties and inform it about their capabilities and technical specifics. While you have the option to operate in a more "promiscuous" way (by enabling profiles for "unverified" RPs), this is relatively rare. In most cases, you will configure metadata sources in order to use the IdP's SAML features; this is done by adding <MetadataProvider>
elements inside the metadata-providers.xml file.
...
xsi:type | Function |
---|---|
A container for multiple A container for an ordered sequence of metadata providers of any type | |
A dynamic provider that fetches metadata just-in-time from a suitably configured HTTP server | |
LocalDynamicMetadataProvider | A dynamic provider that fetches metadata just-in-time from a local source such as a filesystem directory |
A reloading provider that loads (and reloads) a metadata file from the filesystem in a background thread | |
A reloading provider that loads (and reloads) a metadata file from an HTTP server in a background thread | |
HTTPMetadataProvider | DEPRECATED: Use FileBackedHTTPMetadataProvider instead. |
A reloading provider that loads (and reloads) a metadata file from a complex source (such as SVN) in a background thread | |
A provider that allows metadata to be specified inline |
...
Configuration attributes common to two or more metadata providers are listed in the subsections below. Other attributes are specific to the xsi:type
, and these are documented on the pages specific to each type.
Common Attributes
The following attributes are available required on all metadata provider types (except the ChainingMetadataProvider
type):
Name | Type | Default | Description |
---|---|---|---|
id | String | required | Identifier for |
logging, identification for command line reload, etc. | |||
xsi:type | String | required | Specifies the exact type of provider |
to use (from those listed above, or a custom extension type). |
The following attributes are available on all metadata provider types (except the ChainingMetadataProvider
type):
Name | Type | Default | Description |
---|---|---|---|
requireValidMetadata | Boolean | true | Whether candidate metadata found by the resolver must be valid in order to be returned (where validity is implementation specific, but in SAML cases generally depends on a |
failFastInitialization | Boolean | true | Whether to fail initialization of the underlying MetadataResolverService (and possibly the IdP as a whole) if the initialization of a metadata provider fails. When false, the IdP may start, and will continue to attempt to reload valid metadata if configured to do so, but operations that require valid metadata will fail until it does. |
sortKey | Integer | Defines the order in which metadata providers are searched (see below), can only be specified on top level <MetadataProvider> elements. | |
The following are advanced settings supporting a new low-level feature allowing metadata lookup by keys other than the unique entityID and are rarely of use to a deployer. | |||
criterionPredicateRegistryRef 3.3 | Bean ID | Identifies the a custom CriterionPredicateRegistry bean used in resolving predicates from non-predicate input criteria. | |
useDefaultPredicateRegistry 3.3 | Boolean | true | Flag which determines whether the default CriterionPredicateRegistry will be used if a custom one is not supplied explicitly. |
satisfyAnyPredicates 3.3 | Boolean | false | Flag which determines whether predicates used in filtering are connected by a logical 'OR' (true) or by logical 'AND' (false). |
...
You can, if you choose, override this with additional or different files or more advanced sources. Each resource must supply a "top level" <MetadataProvider>
element with attributes and child elements as described above. Search order amongst multiple top level elements is arbitrated by the sortKey
attribute, where lower values are processed before higher ones.
AnchorSearchOrdering SearchOrdering
Search Ordering
SearchOrdering | |
SearchOrdering |
If a specific relying party (as identified by a specific entityID) is duplicated in the metadata sources provided, then which precise entry is chosen is governed by the following rules:
- Metadata sources combined via a chain are searched in the order in which they occur in the chain, and the first entry matching the entityID is returned.
If multiple "top level" Metadata Providers are provided then they are searched in an order derived from the (numeric) value of the
sortKey
attribute (lowest key first). If nosortKey
is specified, then the search order is undefined.- In whatever order of sources is in effect, the first entry matching the entityID is returned.
- If a single metadata source contains multiple entries with the same entityID, then which entry is returned is undefined.
V2 Compatibility
A single <MetadataProvider>
element may be embedded in a legacy relying-party.xml file as described in the older documentation. Consult the V2 documentation for this, and do not mix and match this approach with newer configuration features.
During the V2 to V3 upgrade process, the original V2 relying-party.xml file is copied to metadata-providers.xml, to serve as the metadata configuration for the new version. It's strongly advisable after upgrading to update that file by stripping it of the older content and promote the <MetadataProvider>
element in it to the root of the file. In the interim all other content in the file except for <MetadataProvider>
elements (and any referenced <security:TrustEngine>
elements) is ignored.
The following non-relevant trust engine types often found in a legacy relying-party.xml file are ignored if seen and cannot be used for metadata verification:
Chaining
MetadataExplicitKey
MetadataPKIXX509Credential
MetadataExplicitKeySignature
MetadataPKIXSignature
StaticPKIXX509Credential
New Capabilities in V3
The V3 metadata configuration syntax is backward-compatible with the V2 <MetadataProvider>
syntax and adds some useful new shortcuts.
You can provide multiple metadata configuration files (not just multiple metadata sources in one file), as described above.
When configuring more than one MetadataFilter, you need not wrap them in a "ChainingFilter" filter.
The SignatureValidation filter need not contain a trustEngineRef
attribute referencing a separately-defined trust engine, instead a certificate file may be specified directly with the certificateFile
attribute, or a PEM-format public key may be supplied inline via the <PublicKey>
element. For more advanced requirements, an inline <security:TrustEngine>
element. may be defined.
Note | ||
---|---|---|
| ||
As a child element of the
See the SignatureValidationFilter topic for more information. |