237 lines
9.6 KiB
Text
237 lines
9.6 KiB
Text
|
|
=== Outgoing HTTP requests
|
|
|
|
The {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 <<_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.
|
|
|
|
proxy-mappings::
|
|
Denotes proxy configurations for outgoing HTTP requests.
|
|
See the section on <<_proxymappings, Proxy Mappings for Outgoing HTTP Requests>> for more details.
|
|
|
|
disable-trust-manager::
|
|
If an outgoing request requires HTTPS and this config option is set to `true` you do not have to specify a truststore.
|
|
This setting should only be used during development and *never* in production as it will disable verification of SSL certificates.
|
|
This is _OPTIONAL_.
|
|
The default value is `false`.
|
|
|
|
[[_proxymappings]]
|
|
==== Proxy mappings for outgoing HTTP requests
|
|
|
|
Outgoing HTTP requests sent by {project_name} can optionally use a proxy server based on a comma delimited list of proxy-mappings.
|
|
A proxy-mapping denotes the combination of a regex based hostname pattern and a proxy-uri in the form of `hostnamePattern;proxyUri`,
|
|
e.g.:
|
|
[source]
|
|
----
|
|
.*\.(google|googleapis)\.com;http://www-proxy.acme.com:8080
|
|
----
|
|
|
|
To determine the proxy for an outgoing HTTP request the target hostname is matched against the configured
|
|
hostname patterns. The first matching pattern determines the proxy-uri to use.
|
|
If none of the configured patterns match for the given hostname then no proxy is used.
|
|
|
|
If the proxy server requires authentication, include the proxy user's credentials in this format `username:password@`.
|
|
For example:
|
|
|
|
[source]
|
|
----
|
|
.*\.(google|googleapis)\.com;http://user01:pas2w0rd@www-proxy.acme.com:8080
|
|
----
|
|
|
|
The special value `NO_PROXY` for the proxy-uri can be used to indicate that no proxy
|
|
should be used for hosts matching the associated hostname pattern.
|
|
It is possible to specify a catch-all pattern at the end of the proxy-mappings to define a default
|
|
proxy for all outgoing requests.
|
|
|
|
The following example demonstrates the proxy-mapping configuration.
|
|
|
|
[source]
|
|
----
|
|
# All requests to Google APIs should use http://www-proxy.acme.com:8080 as proxy
|
|
.*\.(google|googleapis)\.com;http://www-proxy.acme.com:8080
|
|
|
|
# All requests to internal systems should use no proxy
|
|
.*\.acme\.com;NO_PROXY
|
|
|
|
# All other requests should use http://fallback:8080 as proxy
|
|
.*;http://fallback:8080
|
|
----
|
|
|
|
This can be configured via the following `jboss-cli` command.
|
|
Note that you need to properly escape the regex-pattern as shown below.
|
|
[source]
|
|
----
|
|
echo SETUP: Configure proxy routes for HttpClient SPI
|
|
|
|
# In case there is no connectionsHttpClient definition yet
|
|
/subsystem=keycloak-server/spi=connectionsHttpClient/provider=default:add(enabled=true)
|
|
|
|
# Configure the proxy-mappings
|
|
/subsystem=keycloak-server/spi=connectionsHttpClient/provider=default:write-attribute(name=properties.proxy-mappings,value=[".*\\.(google|googleapis)\\.com;http://www-proxy.acme.com:8080",".*\\.acme\\.com;NO_PROXY",".*;http://fallback:8080"])
|
|
----
|
|
|
|
The `jboss-cli` command results in the following subsystem configuration.
|
|
Note that one needs to encode `"` characters with `\"`.
|
|
[source,xml]
|
|
----
|
|
<spi name="connectionsHttpClient">
|
|
<provider name="default" enabled="true">
|
|
<properties>
|
|
<property
|
|
name="proxy-mappings"
|
|
value="[".*\\.(google|googleapis)\\.com;http://www-proxy.acme.com:8080",".*\\.acme\\.com;NO_PROXY",".*;http://fallback:8080"]"/>
|
|
</properties>
|
|
</provider>
|
|
</spi>
|
|
----
|
|
|
|
[[_proxy_env_vars]]
|
|
==== Using standard environment variables
|
|
|
|
Alternatively, it is possible to use standard environment variables to configure the proxy mappings, that is `HTTP_PROXY`, `HTTPS_PROXY`
|
|
and `NO_PROXY` variables.
|
|
|
|
The `HTTP_PROXY` and `HTTPS_PROXY` variables represent the proxy server that should be used for all outgoing HTTP requests.
|
|
{project_name} does not differ between the two. If both are specified, `HTTPS_PROXY` takes the precedence regardless of
|
|
the actual scheme the proxy server uses.
|
|
|
|
The `NO_PROXY` variable is used to define a comma separated list of hostnames that should not use the proxy.
|
|
If a hostname is specified, all its prefixes (subdomains) are also excluded from using proxy.
|
|
|
|
Take the following example:
|
|
[source]
|
|
----
|
|
HTTPS_PROXY=https://www-proxy.acme.com:8080
|
|
NO_PROXY=google.com,login.facebook.com
|
|
----
|
|
In this example, all outgoing HTTP requests will use `\https://www-proxy.acme.com:8080` proxy server except for requests
|
|
to for example `login.google.com`, `google.com`, `auth.login.facebook.com`. However, for example `groups.facebook.com` will be routed
|
|
through the proxy.
|
|
|
|
NOTE: The environment variables can be lowercase or uppercase. Lowercase takes precedence. For example if both `HTTP_PROXY` and
|
|
`http_proxy` are defined, `http_proxy` will be used.
|
|
|
|
If proxy mappings are defined using the subsystem configuration (as described above), the environment variables are not
|
|
considered by {project_name}. This scenario applies in case no proxy server should be used despite having for example `HTTP_PROXY`
|
|
environment variable defined. To do so, you can specify a generic no proxy route as follows:
|
|
[source,xml]
|
|
----
|
|
<spi name="connectionsHttpClient">
|
|
<provider name="default" enabled="true">
|
|
<properties>
|
|
<property name="proxy-mappings" value=".*;NO_PROXY"/>
|
|
</properties>
|
|
</provider>
|
|
</spi>
|
|
----
|
|
|
|
[[_truststore]]
|
|
==== Outgoing HTTPS request truststore
|
|
|
|
When {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 {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
|
|
established, 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 <<_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"/>
|
|
</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 any of these properties are defined.
|
|
|
|
password::
|
|
Password of the keystore.
|
|
This is _REQUIRED_ if any of these properties are defined.
|
|
|
|
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.
|
|
|