122 lines
4.9 KiB
Text
Executable file
122 lines
4.9 KiB
Text
Executable file
|
|
=== Outgoing HTTP Requests
|
|
|
|
The {{book.project.name}} server often needs to make non-browser HTTP requests to the applications and services it secures.
|
|
The auth server manages these outgoing connections by maintaining an HTTP client connection pool. There are some things
|
|
you'll need to configure in `standalone.xml`, `standalone-ha.xml`, or `domain.xml`. The location of this file
|
|
depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
|
|
|
|
.HTTP client Config example
|
|
[source,xml]
|
|
----
|
|
<spi name="connectionsHttpClient">
|
|
<provider name="default" enabled="true">
|
|
<properties>
|
|
<property name="connection-pool-size" value="256"/>
|
|
</properties>
|
|
</provider>
|
|
</spi>
|
|
----
|
|
Possible configuration options are:
|
|
|
|
establish-connection-timeout-millis::
|
|
Timeout for establishing a socket connection.
|
|
|
|
socket-timeout-millis::
|
|
If an outgoing request does not receive data for this amount of time, timeout the connection.
|
|
|
|
connection-pool-size::
|
|
How many connections can be in the pool (128 by default).
|
|
|
|
max-pooled-per-route::
|
|
How many connections can be pooled per host (64 by default).
|
|
|
|
connection-ttl-millis::
|
|
Maximum connection time to live in milliseconds.
|
|
Not set by default.
|
|
|
|
max-connection-idle-time-millis::
|
|
Maximum time the connection might stay idle in the connection pool (900 seconds by default). Will start background cleaner thread of Apache HTTP client.
|
|
Set to -`1` to disable this checking and the background thread.
|
|
|
|
disable-cookies::
|
|
`true` by default.
|
|
When set to true, this will disable any cookie caching.
|
|
|
|
client-keystore::
|
|
This is the file path to a Java keystore file.
|
|
This keystore contains client certificate for two-way SSL.
|
|
|
|
client-keystore-password::
|
|
Password for the client keystore.
|
|
This is _REQUIRED_ if `client-keystore` is set.
|
|
|
|
client-key-password::
|
|
Password for the client's key.
|
|
This is _REQUIRED_ if `client-keystore` is set.
|
|
|
|
[[_truststore]]
|
|
==== Outgoing HTTPS Request Truststore
|
|
|
|
When {{book.project.name}} invokes on remote HTTPS endpoints, it has to validate the remote server's certificate in order to ensure it is connecting to a trusted server.
|
|
This is necessary in order to prevent man-in-the-middle attacks. The certificates of these remote server's or the CA that signed these
|
|
certificates must be put in a truststore. This truststore is managed by the {{book.project.name}} server.
|
|
|
|
The truststore is used when connecting securely to identity brokers, LDAP identity providers, when sending emails, and for backchannel communication with client applications.
|
|
|
|
WARNING: By default, a truststore provider is not configured, and any https connections fall back to standard java truststore configuration as described in
|
|
https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html[Java's JSSE Reference Guide]. If there is no trust
|
|
establised, then these outgoing HTTPS requests will fail.
|
|
|
|
You can use _keytool_ to create a new truststore file or add trusted host certificates to an existing one:
|
|
|
|
[source]
|
|
----
|
|
|
|
$ keytool -import -alias HOSTDOMAIN -keystore truststore.jks -file host-certificate.cer
|
|
----
|
|
|
|
The truststore is configured within the `standalone.xml`,
|
|
`standalone-ha.xml`, or `domain.xml` file in your distribution. The location of this file
|
|
depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>.
|
|
You can add your truststore configuration by using the following template:
|
|
|
|
[source,xml]
|
|
----
|
|
<spi name="truststore">
|
|
<provider name="file" enabled="true">
|
|
<properties>
|
|
<property name="file" value="path to your .jks file containing public certificates"/>
|
|
<property name="password" value="password"/>
|
|
<property name="hostname-verification-policy" value="WILDCARD"/>
|
|
<property name="disabled" value="false"/>
|
|
</properties>
|
|
</provider>
|
|
</spi>
|
|
|
|
----
|
|
|
|
Possible configuration options for this setting are:
|
|
|
|
file::
|
|
The path to a Java keystore file.
|
|
HTTPS requests need a way to verify the host of the server they are talking to.
|
|
This is what the trustore does.
|
|
The keystore contains one or more trusted host certificates or certificate authorities.
|
|
This truststore file should only contain public certificates of your secured hosts.
|
|
This is _REQUIRED_ if `disabled` is not true.
|
|
|
|
password::
|
|
Password for the truststore.
|
|
This is _REQUIRED_ if `disabled` is not true.
|
|
|
|
hostname-verification-policy::
|
|
`WILDCARD` by default.
|
|
For HTTPS requests, this verifies the hostname of the server's certificate.
|
|
`ANY` means that the hostname is not verified. `WILDCARD` Allows wildcards in subdomain names i.e.
|
|
*.foo.com. `STRICT` CN must match hostname exactly.
|
|
|
|
disabled::
|
|
If true (default value), truststore configuration will be ignored, and certificate checking will fall back to JSSE configuration as described.
|
|
If set to false, you must configure `file`, and `password` for the truststore.
|
|
|