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
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:
Non-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.
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
This parent bean is available to assist in defining custom HttpClient beans for use with various components:
These two additional parent beans are replacements for the caching clients:
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.
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 might want to copy some of the now-removed bean declarations above from the old V4 system resource 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.)
Some common settings are available as properties (mostly commented out for easy definition in services.properties) and influence the behavior of the internally defined client(s) used by various components to avoid the need for custom configuration. Reusing these properties is a suitable approach if you are fine with all use cases sharing client behavior, and your own beans may chose to reference those properties if you prefer that.
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
Â