Page tree
Skip to end of metadata
Go to start of metadata

The HTTPMetadataProvider and the FileBackedHTTPMetadataProvider load metadata from an HTTP server. Both providers can be configured to periodically check and reload the metadata if needed. This is achieved by configuring the so-called reloading attributes.

The FileBackedHTTPMetadataProvider spools the metadata contents to a local backing file that serves as a secondary source of metadata. If the remote server is unavailable at startup, the backing file is loaded instead and all the configured filters are run on the backing file. If a single filter fails, the backing file is not loaded. If, for example, the signature on the backing file can not be verified, the load operation fails. The startup operation also fails if both MetadataProvider/@failFastInitialization and service property idp.service.metadata.failFast are set to true.

The use of the backing file

As of v3.3.0, the backing file is only used at startup. A refresh operation never consults the backing file since the latter can't possibly represent newer metadata than what is already cached in memory.

Example

Load metadata from a Remote Server
<MetadataProvider id="HTTPMetadata" xsi:type="FileBackedHTTPMetadataProvider"
                  backingFile="%{idp.home}/metadata/localCopyFromXYZHTTP.xml"
                  metadataURL="http://example.org/metadata/metadatafile.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/signer.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="metadata:RequiredValidUntil" maxValidityInterval="P14D"/>

    <!-- Consume all SP metadata in the aggregate -->
    <MetadataFilter xsi:type="EntityRoleWhiteList">
        <RetainedRole>md:SPSSODescriptor</RetainedRole>
    </MetadataFilter>       

</MetadataProvider>

Attributes

Any of the common attributes or the reloading attributes can be specified.  In addition any of the following attributes may be specified.

NameTypeDefaultDescription
metadataURL                       
URLrequiredThe URL that the metadata is served from.
disregardTLSCertificateBooleanfalse

If true this means that no certificate checking will take place on the TLS link.
(incompatible with httpClientRef)

connectionRequestTimeout 3.3Delay (ISO8601 format)PT60S (60 seconds)The maximum amount of time to wait for a connection to be returned from HttpClient's connection pool.
(incompatible with httpClientRef)
requestTimeout deprecated
Delay (ISO8601 format)PT60S (60 seconds)DEPRECATED: Use connectionTimeout, see description there for semantics.
(incompatible with httpClientRef)
connectionTimeout 3.3Delay (ISO8601 format)PT60S (60 seconds)The maximum amount of time to wait to establish a connection with the remote server.
(incompatible with httpClientRef)
socketTimeout 3.3Delay (ISO8601 format)PT60S (60 seconds)The maximum amount of time to wait between two consecutive packets while reading from the socket connected to the remote server.
(incompatible with httpClientRef)
proxyHostString Hostname of the HTTP proxy through which connections will be made
(incompatible with httpClientRef)
proxyPortString Port of the HTTP proxy through which connections will be made.
(incompatible with httpClientRef)
proxyUserString Username used with the HTTP proxy through which connections will be made.
(incompatible with httpClientRef) 
proxyPasswordString Password used with the HTTP proxy through which connections will be made.
(incompatible with httpClientRef) 
basicAuthUserString The user name to provide, during basic authentication, when connecting to the remote server.
(incompatible with httpClientRef) 
basicAuthPasswordString The password to provide, during basic authentication, when connecting to the remote server.
(incompatible with httpClientRef) 
tlsTrustEngineRef 3.1Bean reference 

Specifies the id of a TrustEngine defined elsewhere in the configuration. The Trust Engine may be specified either in custom or spring native bean syntax.
The function of the engine is to XXX
(incopatible with an inline <TLSTrustEngine>)

httpClientRefBean reference 

Specifies the bean id of an externally defined bean which implements org.apache.http.client.HttpClient

This attribute conflicts with and overrides the other HttpClient-related properties: disregardTLSCertificaterequestTimeoutproxyHostproxyPortproxyUser, proxyPassword, httpCaching, httpCacheDirectory, httpMaxCacheEntries, httpMaxCacheEntrySize
httpClientSecurityParametersRef 3.3Bean reference A reference to an externally defined Spring bean which specifies an org.opensaml.security.httpclient.HttpClientSecurityParameters instance, which consolidates all HTTP security parameters, including advanced TLS usage. This can be used instead of basicAuthuser,  basicAuthPassword, and an inline <TLSTrustEngine>.
FILE BACKED PROVIDER ONLY
backingFileFile specificatonrequiredSpecifies where the backing file is located. If the remote server is unavailable at startup, the backing file is loaded.
initializeFromBackupFile 3.3BooleantrueFlag indicating whether initialization should first attempt to load metadata from backup file, if present.  If true, then the foreground initialization will be performed by loading the backing file, and then a refresh from the remote HTTP server will be scheduled to execute in a background thread, after a configured delay. This can improve IdP startup times when the remote HTTP file is large in size.
backupFileInitNextRefreshDelay 3.3Delay (ISO8601 format)PT5S (5 seconds)

Delay duration after which to schedule next HTTP refresh when initialized from backing file.

HTTP CACHING

Note that HTTP caching is a caching system layer inside the HttpClient. It acts independently to the caching-like behavior of the FileBackedHTTPMetadataProvider
httpCaching"none", "file" or "memory"
(cannot be specified by a property) 
noneSpecifies whether caching is to be performed by the http client or not. If so there are two choices:
  • "file' indicates that the cache is to disk (as it is in a browser) and that outlives the lifetime of the IdP. 
  • "memory" indicates that the cache is volatile.
    (incompatible with httpClientRef) 
httpCacheDirectory  If httpCaching="file" is specified this specifies where retrieved files are to be cached.
(incompatible with httpClientRef) 
httpMaxCacheEntries 

memory: 50

file: 100

The maximum number of responses to cache.
(incompatible with httpClientRef) 
httpMaxCacheEntrySize 

memory: 1048576 (1MB)

file:  10485760 (10MB)

The maximum response body size which may be cached, in bytes.
(incompatible with httpClientRef)
 

Child Elements

Any of the common child elements can be specified.  After these, a <TLSTrustEngine>3.1 may be added

  • No labels