Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device. Atlassian cookies and tracking notice, (opens new window)
The Shibboleth IdP generally requires SAML metadata to provision connectivity with SAML 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 not a common operating mode. 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.
Note that the other protocol(s) supported by the IdP generally support, but not strictly require, the use of SAML metadata, alongside other protocol-specific means of handling the same kinds of functions. Use of metadata enables a variety of useful configuration techniques that are superior to the features available from other approaches to managing relying parties and is generally advisable.
A typical use case is to load (and periodically reload) entity metadata from a local file:
<!--
Load (and reload) entity metadata from a local file.
The metadata refresh process is determined by the configured values of the
minRefreshDelay attribute (default: PT30S) and maxRefreshDelay attribute
(default: PT4H). If you want to load (or reload) the metadata immediately,
restart the IdP.
-->
<MetadataProvider id="LocalEntityMetadata" xsi:type="FilesystemMetadataProvider"
metadataFile="%{idp.home}/metadata/local-metadata.xml"/>
Another use case is to load (and periodically reload) a metadata aggregate from a remote source via HTTP:
<!--
Load (and reload) a signed metadata aggregate from a remote HTTP server.
This sample configuration assumes: (1) the top-level element of the XML
document is signed; (2) the top-level element of the XML document is
decorated with a validUntil attribute; (3) the validity interval is two
weeks (P14D) in duration; and (4) the server supports HTTP conditional GET.
The metadata refresh process is influenced by the configured values of
the minRefreshDelay attribute (default: PT30S) and the maxRefreshDelay
attribute (default: PT4H) and also by any cacheDuration and validUntil
attributes in the metadata itself. If the server does not support HTTP
conditional GET, the attributes should be adjusted accordingly.
-->
<MetadataProvider id="RemoteMetadataAggregate" xsi:type="FileBackedHTTPMetadataProvider"
backingFile="%{idp.home}/metadata/federation-metadata-copy.xml"
metadataURL="http://example.org/metadata/federation-metadata.xml">
<!--
Verify the signature on the root element of the metadata aggregate
using a trusted metadata signing certificate.
-->
<MetadataFilter xsi:type="SignatureValidation" requireSignedRoot="true"
certificateFile="%{idp.home}/conf/metadata/md-cert.pem"/>
<!--
Require a validUntil XML attribute on the root element and
make sure its value is no more than 14 days into the future.
-->
<MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P14D"/>
<!-- Consume all SP metadata in the aggregate -->
<MetadataFilter xsi:type="EntityRole">
<RetainedRole>md:SPSSODescriptor</RetainedRole>
</MetadataFilter>
</MetadataProvider>
But increasingly, the dynamic providers (LocalDynamicMetadataProvider and DynamicHTTPMetadataProvider) are used in lieu of the reloading providers (FilesystemMetadataProvider and FileBackedHTTPMetadataProvider) shown above. See the MetadataManagementBestPractices topic for use cases and recommendations.
The ChainingMetadataProvider is often used to combine two or more metadata sources. The metadata-providers.xml file that ships with the software includes such a chain "wrapper" by default.
Namespaces and Schemas
Nearly all elements described in this page and its children are defined in the urn:mace:shibboleth:2.0:metadata namespace, the schema for which can be located at http://shibboleth.net/schema/idp/shibboleth-metadata.xsd. Throughout this document and its children, this is assumed to be the default XML namespace in effect. The namespace prefix "metadata:" is conventionally also bound to this namespace.
The namespace prefix "security:" is used to refer to the urn:mace:shibboleth:2.0:security namespace, the schema for which can be located at http://shibboleth.net/schema/idp/shibboleth-security.xsd, and is generally used only in advanced scenarios or for compatibility.
The precise behavior of any <MetadataProvider> element is controlled by the xsi:type attribute (see below). The following types are supported and examples are provided for each type. If the urn:mace:shibboleth:2.0:metadata namespace is not the default, then a prefix (presumably "metadata:") is required when specifying these types.
A provider that allows metadata to be specified inline
Reference
Configuration options common to two or more metadata providers are listed in the subsections below. Others are specific to the xsi:type, and these are documented on the pages specific to each type.
Name
Type
Default
Description
Name
Type
Default
Description
The following attributes are required on all metadata provider types:
id
String
Identifier for logging, identification for command line reload, etc.
xsi:type
String
Specifies the exact type of provider to use (from those listed above, or a custom extension type)
The following attributes are common to all metadata provider types except the ChainingMetadataProvider type:
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 validUntil attribute.) If this flag is true, then invalid candidate metadata will not be returned.
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.
metricsBaseName
String
Overrides the default name of the metrics reported out by various metadata providers.
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
Bean ID
Identifies the a custom CriterionPredicateRegistry bean used in resolving predicates from non-predicate input criteria
useDefaultPredicateRegistry
Boolean
true
Flag which determines whether the default CriterionPredicateRegistry will be used if a custom one is not supplied explicitly
satisfyAnyPredicates
Boolean
false
Flag which determines whether predicates used in filtering are connected by a logical 'OR' (true) or by logical 'AND' (false)
Lower bound on the next refresh from the time calculated based on the metadata's expiration
maxRefreshDelay
Duration
PT4H
Upper bound on the next refresh from the time calculated based on the metadata's expiration
refreshDelayFactor
Real Number (strictly between 0.0 and 1.0)
0.75
A factor applied to the initially determined refresh time in order to determine the next refresh time (typically to ensure refresh takes place prior to the metadata's expiration). Attempts to refresh metadata will generally begin around the product of this number and the maximum refresh delay.
expirationWarningThreshold
Duration
PT0S (disabled)
For each attempted metadata refresh (whether or not fresh metadata is obtained), if requireValidMetadata is true, and there is a validUntil XML attribute on the document root element, and the difference between validUntil and the current time is less than expirationWarningThreshold, the system logs a warning about the impending expiration.
indexesRef
Bean ID
Bean ID of a Set<MetadataIndex> used to support resolution of metadata based on criteria other than an entityID, e.g. resolving by protocol endpoint for CAS or by SAML Artifact source ID.
resolveViaPredicatesOnly
Boolean
false
Flag indicating whether resolution may be performed solely by applying predicates to the entire metadata collection, when an entityID input criterion is not supplied
parserPoolRef
Bean ID
shibboleth.ParserPool
Identifies a Spring bean for the XML parser used to parse metadata. Generally should not be changed.
taskTimerRef
Bean ID
Identifies a Spring bean containing a Java Timer used to schedule reloads. When not set, an internal one is created. Generally should not be changed.
Identifies a Spring bean for the XML parser used to parse metadata. Generally should not be changed.
taskTimerRef
Bean ID
Identifies a Spring bean containing a Java TaskTimer used to schedule reloads. When not set, an internal timer is created. Generally should not be changed.
refreshDelayFactor
Real Number (strictly between 0.0 and 1.0)
0.75
A factor applied to the initially determined refresh time in order to determine the next refresh time (typically to ensure refresh takes place prior to the metadata's expiration). Attempts to refresh metadata will generally begin around the product of this number and the maximum refresh delay.
minCacheDuration
Duration
PT10M
The minimum duration for which metadata will be cached before it is refreshed
maxCacheDuration
Duration
PT8H
The maximum duration for which metadata will be cached before it is refreshed
maxIdleEntityData
Duration
PT8H
The maximum duration for which metadata will be allowed to be idle (no requests for it) before it is removed from the cache
removeIdleEntityData
Boolean
true
Flag indicating whether idle metadata should be removed
cleanupTaskInterval
Duration
PT30M
The interval at which the internal cleanup task should run. This task performs background maintenance tasks, such as the removal of expired and idle metadata.
persistentCacheManagerRef
Bean ID
The optional manager for the persistent cache store for resolved metadata. On metadata provider initialization, data present in the persistent cache will be loaded to memory, effectively restoring the state of the provider as closely as possible to that which existed before the previous shutdown. Each individual cache entry will only be loaded if 1) the entry is still valid as determined by the internal provider logic, and 2) the entry passes the (optional) predicate supplied via initializationFromCachePredicateRef.
persistentCacheManagerDirectory
Directory path
The directory used for an internally-constructed filesystem-based persistent cache. This is a convenience parameter to avoid specifying a full bean via persistentCacheManagerRef. This option will be ignored if persistentCacheManagerRef is specified.
NOTE: Do NOT specify a directory containing other metadata or any other content under local control, as the cache manager may alter those files, or fail to process them correctly, or both. Use a dedicated directory for each provider.
persistentCacheKeyGeneratorRef
Bean ID
internal default instance
Identifies a Spring bean for a Function which generates the string key used with the cache manager. The default implementation produces the lower-case hex-encoded SHA-1 digest of the entityID of the EntityDescriptor.
initializeFromPersistentCacheInBackground
Boolean
true
Flag indicating whether should initialize from the persistent cache in the background. Initializing from the cache in the background will improve IdP startup times.
backgroundInitializationFromCacheDelay
Duration
PT2S
The delay after which to schedule the background initialization from the persistent cache when initializeFromPersistentCacheInBackground=true.
initializationFromCachePredicateRef
Bean ID
"always true" predicate
Identifies a Spring bean for an optional Predicate which determines whether a given entity should be loaded from the persistent cache at resolver initialization time.
An HTTP metadata provider includes a default implementation of an HttpClient to use. The attributes in the following subsections control the behavior of the default HTTP client. In most cases, the default behavior is sufficient.
To override the default client implementation, configure the following attribute:
Name
Type
Description
Name
Type
Description
httpClientRef
Bean ID
A reference to an externally defined Spring bean that specifies an HttpClient object. This attribute conflicts with and overrides all of the other HTTP attributes. See the HttpClientConfiguration topic for more information.
Use of the httpClientRef attribute precludes the use of any and all of the HTTP attributes in the following subsections.
The following attributes apply to the HTTP connections obtained and managed by an HTTP metadata provider:
Name
Type
Default
Description
Name
Type
Default
Description
connectionRequestTimeout
Duration
Depends on provider type
The maximum amount of time to wait for a connection to be returned from the HTTP client's connection pool manager. Set to PT0S to disable.
connectionTimeout
Duration
Depends on provider type
The maximum amount of time to wait to establish a connection with the remote server. Set to PT0S to disable.
socketTimeout
Duration
Depends on provider type
The maximum amount of time to wait between two consecutive packets while reading from the socket connected to the remote server. Set to PT0S to disable.
NOTE: This is NOT an aggregate timeout on the whole request but merely between packets. For that responseTimeout is available, starting in 5.2.
responseTimeout 5.2
Duration
Depends on provider type
The maximum amount of time to wait until a response from the remote server. Set to PT0S to disable.
requestTimeout 5.2
Duration
Depends on provider type
The maximum allowed length of time for the entire request/response operation to complete.
requestTimeoutCorePoolSize 5.2
Integer
20
The core pool size of the ScheduledExecutorService used to implement requestTimeout handling.
This is the number of threads to keep in the pool, even if they are idle. The total number of threads in the pool is allowed to grow up to the max integer value.
The following security-related attributes apply to any HTTP metadata provider:
Name
Type
Default
Description
Name
Type
Default
Description
disregardTLSCertificate
Boolean
false
If true, no TLS certificate checking will take place over an HTTPS connection.
Be careful with this setting, it is typically only used during testing. See the HttpClientConfiguration topic for more information.
httpClientSecurityParametersRef
Bean ID
A reference to an externally defined Spring bean that specifies an HttpClientSecurityParameters instance, which consolidates all HTTP security parameters including advanced TLS usage.
In 5.0, this attribute conflicts with and overrides any explicit TrustEngine implementation configured as an inline <TLSTrustEngine> element. See the HttpClientConfiguration topic for more information.
In 5.1, if an inline trust engine is specified, it will be merged into any supplied instance.
The following attributes configure an HTTP proxy for use with an HTTP metadata provider:
Name
Type
Description
Name
Type
Description
proxyHost
String
The hostname of the HTTP proxy through which connections will be made
proxyPort
String
The port of the HTTP proxy through which connections will be made
proxyUser
String
The username used with the HTTP proxy through which connections will be made
proxyPassword
String
The password used with the HTTP proxy through which connections will be made
The following child element is common to all MetadataProvider types except the ChainingMetadataProvider type:
A metadata filter applied to candidate metadata as it flows through the metadata pipeline
Miscellany
As described in the ReloadableServices documentation, the configuration is actually loaded from a bean whose name is specified by the property idp.service.metadata.resources, with the default value shibboleth.MetadataResolverResources (in turn defined in conf/services.xml to be a list with one entry: the file metadata-providers.xml)
You can, if you choose, override this with additional or different files or more advanced sources. Each resource usually is expected to 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.
It is also now possible to declare "by reference" metadata filters that are attached by reference, so it is possible to supply a resource whose top-level element is such a <MetadataFilter> in such cases.
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 no sortKey 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 (exception: invalid entries would be ignored in favor of valid ones in most cases).