The Shibboleth IdP V4 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP5 wiki space for current documentation on the supported version.
HttpClientConfiguration
Overview
The IdP software uses the Apache HttpClient library more or less anywhere that this functionality is required, which for most deployers is confined to obtaining metadata from remote sources. The necessary settings to control the behavior of the metadata client code can be handled directly in the metadata-providers.xml file in most cases, so this topic is primarily a reference for people who have very advanced needs or are using other components and features that make use of HTTP clients.
Some of the components that require or at least support the injection of a custom client bean include:
the HTTPConnector for web service access in the attribute resolver
connectivity to Duo's AuthAPI for non-browser use
CAS proxy validation
loading service configuration resources from an HTTP server (HTTPResource)
advanced/custom configuration of remote metadata sources (FileBackedHTTPMetadataProvider, DynamicHTTPMetadataProvider)
reporting of metrics via an HTTP collector (MetricsConfiguration)
You might need to dive into this topic further if you want to finely tune settings for different situations or if you have advanced security requirements that go beyond default behavior. A common example would be if you want to control TLS server authentication at a finely-grained level to avoid dependence on the default trust behavior of Java's TLS implementation. This is particularly true if you ever find yourself modifying the "global" Java trust store. That should never be done, since it makes Java upgrades much more troublesome.
In comparison to some of the IdP's features, the veneer here is very "thin". That is, we don't have a lot of layers of abstraction and simplification in place to hide the gory details (this may come as news, but much of the rest of the configuration is very abstracted and simplified from what it could look like).
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.InMemoryCachingHttpClientFactoryBean
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.
In the vast majority of cases, we strongly recommend sticking with the non-caching one (the first one). The other two don't really provide benefits in most use cases and they tend to behave unexpectedly and they interfere with commonly-used components that already provide HTTP caching features or file backups for resiliency.
Built-In Clients
There were a set of built-in client beans defined prior to V4 that exposed a bug in Spring that remains unfixed; as such, we strongly advise NOT relying on the following deprecated beans when defining your own clients:
shibboleth.NonCachingHttpClient
shibboleth.FileCachingHttpClient
shibboleth.MemoryCachingHttpClient
We instead suggest relying on a new set of parent beans (the link will take you to the relevant javadoc):
However, be advised that these beans merely simplify the declaration of the underlying class, and do NOT predefine any properties or non-default behavior at all. You must define any settings you wish to use yourself. You may wish to copy the deprecated bean declarations above from the underlying system resources for your own use, but you should use the new parent beans and define separate clients for any use case for which you want to customize the behavior. (Sharing a single client bean across different components generally can work, but when this happens across different reloadable services, an unfixed Spring bug becomes a problem.)
Many common settings are available as properties (mostly commented out for easy definition in services.properties).These properties are a mix of global settings that configure each client type and specific settings controlling the caching behavior of the individual types. This is a suitable approach if you have one use case, or are fine with all use cases sharing client behavior, and your own beans may chose to reference those properties if you prefer that approach.
Security Configuration
A common use for advanced configuration is to control the server certificate evaluation process. While the IdP typically relies on SAML metadata for this when communicating with servers, this doesn't work for a lot of non-SAML use cases. However, much of the same machinery can be repurposed to support a variety of trust models, and we have integrated this into the HttpClient library. Another use case is to support HTTP authentication such as a name and password to access a resource.
Reference
Â