...
A particularly useful approach is to abandon the fundamentally flawed use of commercial certificates with non-browser-facing services and use self-signed certificates evaluated on the basis of public key comparisons, much like Shibboleth does with SAML, or even certificates issued on an automated short-term basis by dedicated CAs.
| Note |
|---|
You need to be careful with this, because leaving out a step can introduce security holes. In particular, if If you want an HttpClient bean to use the special TLSSocketFactory we provide that supports a TrustEngine, you MUST provide an HttpClientSecurityParameters instance to the component using the HttpClient bean to configure the security behavior you want. Failure to do so will prevent TLS socket connections from succeeding in V3.4, but only results in warnings on earlier versions. |
Repeating: you can tell the HttpClient bean that you want to support a more "advanced mode" of processing, but you configure the rules not on the HttpClient bean but rather on the component using the client bean. This is because the injection of the rules you want to apply have to be added at runtime when the client gets used and not into the client's own data structures. It's a consequence of the library's design. The risk in versions of the software prior to V3.4 is that if you tell the client you want this, but don't configure the component that's using it properly, the default Java behavior is also skipped, and you get no security at all. The following explains what you should do, in detail.
...
The examples below are semi-complete, in that they include a portion of the "real" component that the security rules are being supplied for. Most of the components that can support this will carry both httpClient and httpClientSecurityParameters properties. Components defined in custom (non-Spring) XML syntax will usually support httpClientRef and httpClientSecurityParametersRef XML attributes to reference Spring beans of the proper type.
...
The full range of PKIX options is quite complex, but for basic use cases a factory bean makes it simple. To validate the server's certificate against a fixed CA (name checking is turned off because the HttpClient is already doing this step for us):
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<bean id="CustomHttpSecurity" class="org.opensaml.security.httpclient.HttpClientSecurityParameters">
<property name="tLSTrustEngine">
<bean parent="shibboleth.StaticPKIXTrustEngine"
p:certificates="%{idp.home}/credentials/rootca.pem"
p:checkNames="false" />
</property>
</bean>
<!-- Sample feature we're actually trying to use, which we inject custom rules into. -->
<bean id="PushReporter" parent="shibboleth.metrics.HTTPReporter" c:name="MyCollector"
p:httpClient-ref="CustomHttpClient"
p:httpClientSecurityParameters-ref="CustomHttpSecurity"
p:collectorURL="https://log.example.org/cgi-bin/collector.cgi" /> |
...
Applying a TrustEngine to HttpClient
You should always start by configuring a component using the HttpClient with the HttpClientSecurityParameters wiring needed to implement your needs, as in the above examples.
...
| Name | Type | Description |
|---|---|---|
shibboleth.NonCachingHttpClient NonCachingHttpClient | HttpClientFactoryBean | Factory bean for non-caching HTTP client |
| shibboleth.FileCachingHttpClient | FileCachingHttpClientFactoryBean | Factory bean for file-based-caching HTTP client |
shibboleth.MemoryCachingHttpClient | InMemoryCachingHttpClientFactoryBean | Factory bean for in-memory-caching HTTP client |
| shibboleth.StaticExplicitTrustEngine 3.3 | StaticExplicitKeyFactoryBean | Factory bean for creating ExplicitKeyTrustEngine |
| shibboleth.StaticPKIXTrustEngine 3.3 | StaticPKIXFactoryBean | Factory bean for creating PKIXX509CredentialTrustEngine |
| shibboleth.SecurityEnhancedTLSSocketFactory 3.2 | SecurityEnhancedTLSSocketFactory | Socket factory that supports HttpClientSecurityParameters-aware components |
| shibboleth.SecurityEnhancedTLSSocketFactoryWithClientTLS 3.3 | SecurityEnhancedTLSSocketFactory | Client-TLS-capable socket factory that supports HttpClientSecurityParameters-aware components |
| shibboleth.SecurityEnhancedTLSSocketFactoryWithClientTLSOnly 3.4 | SecurityEnhancedTLSSocketFactory | Client-TLS-capable socket factory that supports HttpClientSecurityParameters-aware components but does not accept a pluggable TrustEngine |
Properties
| Name | Type | Default | Description |
|---|---|---|---|
| idp.httpclient.useSecurityEnhancedTLSSocketFactory 3.2 | 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 (one min) | TIme to wait for a connection to be returned from the pool (can be 0 for no imposed value) |
| idp.httpclient.connectionTimeout | Duration | PT1M (one min) | TIme to wait for a connection to be established (can be 0 for no imposed value) |
| idp.httpclient.socketTimeout | Duration | PT1M (one min) | Time to allow between packets on a connection (can be 0 for no imposed value) |
| 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 | Largest size to allow for an in-memory cache entry |
| idp.httpclient.filecaching.maxCacheEntries | Integer | 100 | Size of the non-disk result cache |
| idp.httpclient.filecaching.maxCacheEntrySize | Long | 10485760 | Largest sze to allow for an on-disk cache entry |
| idp.httpclient.filecaching.cacheDirectory | Local directory | Location of on-disk cache |