113 lines
4.5 KiB
Text
Executable file
113 lines
4.5 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 thing
|
|
you'll need to configure in the _keycloak-server.json_. Where this file lives depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>
|
|
|
|
|
|
.keycloak-server.json HTTP client Config
|
|
[source,json]
|
|
----
|
|
"connectionsHttpClient": {
|
|
"default": {}
|
|
},
|
|
----
|
|
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_keycloak-server.json_ file. 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]
|
|
----
|
|
|
|
"truststore": {
|
|
"file": {
|
|
"file": "path to your .jks file containing public certificates",
|
|
"password": "password",
|
|
"hostname-verification-policy": "WILDCARD",
|
|
"disabled": false
|
|
}
|
|
}
|
|
----
|
|
|
|
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.
|
|
|