keycloak-scim/topics/network/outgoing.adoc

=== 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.