Page Comparison

...

As a result, this topic is heavy on examples, and going beyond the examples is more a case of reading javadocs and finding the right settings than reading some documentation to magically impart the right answer.

General Configuration

A set of Spring factory beans are provided that understand how to build an HttpClient instance with a variety of features and settings. For technical reasons the basic caching behavior of the client is determined by selecting from among three different factory bean types:

net.shibboleth.idp.profile.spring.relyingparty.metadata.HttpClientFactoryBean
net.shibboleth.idp.profile.spring.relyingparty.metadata.FileCachingHttpClientFactoryBean
net.shibboleth.idp.profile.spring.relyingparty.metadata.InMemoryCachingHttpClientFactoryBeanNon-Caching
File-based Caching
In-memory Caching

As you would expect, the first provides no explicit caching of results, the second caches results on disk (but not across restarts of the software), and the third caches results in memory. This is HTTP caching; that is, it relies on signaling between the client and web server to detect when to reuse results and supports conditional GET requests with cache control headers to redirect requests into the cache. Essentially they act much like a browser would.

...

This parent bean is available to assist in defining custom HttpClient beans for use with various components:

shibboleth.HttpClientFactory

Note

These two additional parent beans are replacements for the caching clients:

We Again, we don’t advise using the caching variants in most cases, as they do not behave in the ways most people have tended to expect, and the dominant use cases for these clients is not with larger documents that benefit from this caching. Metadata resolvers, for example, do not rely on these beans at all because the caching is tailored to those use cases and implemented directly.

...

Expand

title	HTTP Authentication

Note
This material has changed with V5 due to changes in the underlying HttpClient library and the original examples from V4 do not work for this release.

There is now official support for Basic Authentication using our APIs. Other HTTP authentication mechanisms may work but likely require interacting with lower-level HttpClient library objects.

The supported API for this involves injecting a map keyed by HttpHost objects whose value is the username and password to use. This API supports pre-emptive authentication; that is, the code will offer the credentials automatically when contacting the specified host and will not wait for a challenge from the server to do so. It should therefore be used only with TLS-protected hosts with appropriate verification, as described earlier.

We have defined a pair of parent beans to abstract some of the classes needed to define the map:

shibboleth.HttpHost – a parent bean that wraps the Apache client’s HttpHost class
shibbleth.BasicAuthCredentials – a parent bean that wraps the Apache client’s UsernamePasswordCredentials class

The map must be injected into the HttpClientSecurityParameters bean via the preemptiveBasicAuthMap property.

Example of Basic Authentication along with TLS Verification

Code Block

language	xml

<bean id="CustomHttpSecurity" class="org.opensaml.security.httpclient.HttpClientSecurityParameters"
        p:preemptiveBasicAuthMap-ref="restAuthMap">
	<property name="tLSTrustEngine">
		<bean parent="shibboleth.StaticExplicitTrustEngine"
			p:certificates="%{idp.home}/credentials/server.pem" />
	</property>
</bean>

<util:map id="restAuthMap">
    <entry>
        <key>
            <bean parent="shibboleth.HttpHost"
                p:scheme="https" p:hostname="rest.service.example.org" p:port="443" />
        </key>
        <bean parent="shibboleth.BasicAuthCredentials"
            p:username="%{rest.username}" p:password="%{rest.password}" />
    </entry>
</util:map>

Since the map discriminates the credentials by host, it’s safe to define all your various credentials in one map and use it wherever needed.

Expand

title	HTTP Proxy

The HTTPClientBuilder object that is the base for the HTTPClient beans has properties for HTTP proxy settings:

Code Block

language	xml

 <bean id="my.HttpClient" parent="shibboleth.HttpClientFactory"
    p:connectionProxyHost="proxy.example.org"
    p:connectionProxyPort="3128" />

Reference

Expand

title	Properties

These properties are used in a set of DEPRECATED parent beans that are no longer supported due to a Spring bug that can impact the reloading of service configurations. They remain present for compatibility and for convenience should you choose to use them in your own bean definitions

Name	Type	Default	Description
idp.httpclient.useSecurityEnhancedTLSSocketFactory	Boolean	false	If true, causes the default clients to be injected with a special socket factory that supports advanced TLS features (requires substantial additional configuration)
idp.httpclient.connectionDisregardTLSCertificate	Boolean	false	If the previous property is false, this allows the default TLS behavior of the client to ignore the TLS server certificate entirely (use with obvious caution, typically only while testing)
idp.httpclient.connectionRequestTimeout	Duration	PT1M	TIme to wait for a connection to be returned from the pool (can be 0 for no imposed value)
idp.httpclient.connectionTimeout	Duration	PT1M	TIme to wait for a connection to be established (can be 0 for no imposed value)
idp.httpclient.socketTimeout	Duration	PT1M	Time to allow between packets on a connection (can be 0 for no imposed value) NOTE: This is NOT an aggregate timeout on the whole request but merely between packets. There is no aggregate request timeout at present as the Apache library doesn’t support it.
idp.httpclient.maxConnectionsTotal	Integer	100	Caps the number of simultaneous connections created by the pooling connection manager
idp.httpclient.maxConnectionsPerRoute	Integer	100	Caps the number of simultaneous connections per route created by the pooling connection manager
idp.httpclient.memorycaching.maxCacheEntries	Integer	50	Size of the in-memory result cache
idp.httpclient.memorycaching.maxCacheEntrySize	Long	1048576 (1MB)	Largest size to allow for an in-memory cache entry
idp.httpclient.filecaching.maxCacheEntries	Integer	100	Size of the on-disk result cache
idp.httpclient.filecaching.maxCacheEntrySize	Long	10485760 (10MB)	Largest sze to allow for an on-disk cache entry
idp.httpclient.filecaching.cacheDirectory	Local directory		Location of on-disk cache

Expand

title	Beans

Name	Type	Description
shibboleth.HttpClientFactory	HttpClientFactoryBean	Parent for creating custom client beans
shibboleth.FileCachingHttpClientFactory	FileCachingHttpClientFactoryBean	Parent for creating custom client beans
shibboleth.MemoryCachingHttpClientFactory	InMemoryCachingHttpClientFactoryBean	Parent for creating custom client beans
shibboleth.StaticExplicitTrustEngine	StaticExplicitKeyFactoryBean	Factory bean for creating ExplicitKeyTrustEngine
shibboleth.StaticPKIXTrustEngine	StaticPKIXFactoryBean	Factory bean for creating PKIXX509CredentialTrustEngine
shibboleth.SecurityEnhancedTLSSocketFactory	SecurityEnhancedTLSSocketFactory	Socket factory that supports HttpClientSecurityParameters-aware components
shibboleth.SecurityEnhancedTLSSocketFactoryWithClientTLS	SecurityEnhancedTLSSocketFactory	Client-TLS-capable socket factory that supports HttpClientSecurityParameters-aware components
shibboleth.SecurityEnhancedTLSSocketFactoryWithClientTLSOnly	SecurityEnhancedTLSSocketFactory	Client-TLS-capable socket factory that supports HttpClientSecurityParameters-aware components but does not accept a pluggable TrustEngine
shibboleth.HttpHost	HttpHost	Parent bean for creating host specifiers for basic authentication
shibboleth.BasicAuthCredentials	UsernamePasswordCredentials	Parent bean for defining basic authentication credentials

...

Versions Compared

Old Version 5

New Version Current

Key

General Configuration

Example of Basic Authentication along with TLS Verification

Reference