=== Setting Up a Load Balancer or Proxy

This section discusses a number of things you need to configure before you can put a reverse proxy or load balancer
in front of your clustered {{book.project.name}} deployment.  It also covers configuring the built in load balancer that
was <<fake/../../operating-mode/domain.adoc#_clustered-domain-example, Clustered Domain Example>>.


==== Identifying Client IP Addresses

A few features in {{book.project.name}} rely on the fact that the remote
address of the HTTP client connecting to the authentication server is the real IP address of the client machine.  This can
be problematic when you have a reverse proxy or loadbalancer in front of your {{book.project.name}} authentication server.
The usual setup is that you have a frontend proxy sitting on a public network that load balances and forwards requests
to backend {{book.project.name}} server instances located in a private network.  There is some extra configuration you have to do in this scenario
so that the actual client IP address is forwarded to and processed by the {{book.project.name}} server instances.  Specifically:

* Configure your reverse proxy or loadbalancer to properly set `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers.
* Configure your reverse proxy or loadbalancer to preserve the original 'Host' HTTP header.
* Configure the authentication server to read the client's IP address from `X-Forwarded-For header`.

Configuring your proxy to generate the `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers and preserving the
 original `Host` HTTP header is beyond the scope of this guide.  Take extra precautions to ensure that the
`X-Forwared-For` header is set by your proxy.  If your proxy isn't configured correctly, then _rogue_ clients can set this header themselves and trick {{book.project.name}}
into thinking the client is connecting from a different IP address than it actually is.  This becomes really important if you are doing
any black or white listing of IP addresses.

Beyond the proxy itself, there are a few things you need to configure on the {{book.project.name}} side of things.
If your proxy is forwarding requests via the HTTP protocol, then you need to configure {{book.project.name}} to pull the client's
IP address from the `X-Forwarded-For` header rather than from the network packet.
To do this, open up the profile configuration file (_standalone.xml_, _standalone-ha.xml_, or _domain.xml_ depending on your
<<fake/../../operating-mode.adoc#_operating-mode, operating mode>>) and look for the `"urn:jboss:domain:undertow:3.0` XML block.

.`X-Forwarded-For` HTTP Config
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:undertow:3.0">
   <buffer-cache name="default"/>
   <server name="default-server">
      <ajp-listener name="ajp" socket-binding="ajp"/>
      <http-listener name="default" socket-binding="http" redirect-socket="https"
          proxy-address-forwarding="true"/>
      ...
   </server>
   ...
</subsystem>
----

Add the `proxy-address-forwarding` attribute to the `http-listener` element.  Set the value to `true`.

If your proxy is using the AJP protocol instead of HTTP to forward requests (i.e. Apache HTTPD + mod-cluster), then you have
to configure things a little differently.  Instead of modifying the `http-listener`, you need to add a filter to
pull this information from the AJP packets.


.`X-Forwarded-For` AJP Config
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:undertow:3.0">
     <buffer-cache name="default"/>
     <server name="default-server">
         <ajp-listener name="ajp" socket-binding="ajp"/>
         <http-listener name="default" socket-binding="http" redirect-socket="https"/>
         <host name="default-host" alias="localhost">
             ...
             <filter-ref name="proxy-peer"/>
         </host>
     </server>
        ...
     <filters>
         ...
         <filter name="proxy-peer"
                 class-name="io.undertow.server.handlers.ProxyPeerAddressHandler"
                 module="io.undertow.core" />
     </filters>
 </subsystem>
----

==== Enable HTTPS/SSL with a Reverse Proxy

Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port HTTPS traffic is redirected to.
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:undertow:3.0">
    ...
    <http-listener name="default" socket-binding="http"
        proxy-address-forwarding="true" redirect-socket="proxy-https"/>
    ...
</subsystem>
----

Add the `redirect-socket` attribute to the `http-listener` element.  The value should be `proxy-https` which points to a
socket binding you also need to define.

Then add a new `socket-binding` element to the `socket-binding-group` element:

[source,xml]
----

<socket-binding-group name="standard-sockets" default-interface="public"
    port-offset="${jboss.socket.binding.port-offset:0}">
    ...
    <socket-binding name="proxy-https" port="443"/>
    ...
</socket-binding-group>
----

==== Verify Configuration

You can verify the reverse proxy or load balancer configuration by opening the path `/auth/realms/master/.well-known/openid-configuration`
through the reverse proxy. For example if the reverse proxy address is `https://acme.com/` then open the URL
`https://acme.com/auth/realms/master/.well-known/openid-configuration`. This will show a JSON document listing a number
of endpoints for {{book.project.name}}. Make sure the endpoints starts with the address (scheme, domain and port) of your
reverse proxy or load balancer. By doing this you make sure that {{book.project.name}} is using the correct endpoint.

You should also verify that {{book.project.name}} sees the correct source IP address for requests. Do check this you can
try to login to the admin console with an invalid username and/or password. This should show a warning in the server log
something like this:

[source]
----
08:14:21,287 WARN  XNIO-1 task-45 [org.keycloak.events] type=LOGIN_ERROR, realmId=master, clientId=security-admin-console, userId=8f20d7ba-4974-4811-a695-242c8fbd1bf8, ipAddress=X.X.X.X, error=invalid_user_credentials, auth_method=openid-connect, auth_type=code, redirect_uri=http://localhost:8080/auth/admin/master/console/?redirect_fragment=%2Frealms%2Fmaster%2Fevents-settings, code_id=a3d48b67-a439-4546-b992-e93311d6493e, username=admin
----

Check that the value of `ipAddress` is the IP address of the machine you tried to login with and not the IP address
 of the reverse proxy or load balancer.

==== Using the Built-In Load Balancer

This section covers configuring the built in load balancer that is discussed in the
<<fake/../../operating-mode/domain.adoc#_clustered-domain-example, Clustered Domain Example>>.

The <<fake/../../operating-mode/domain.adoc#_clustered-domain-example, Clustered Domain Example>> is only designed to run
on one machine.  To bring up a slave on another host, you'll need to

. Edit the _domain.xml_ file to point to your new host slave
. Copy the server distribution.  You don't need the _domain.xml_, _host.xml_, or _host-master.xml_ files.  Nor do you need
  the _standalone/_ directory.
. Edit the _host-slave.xml_ file to change the bind addresses used or override them on the command line



===== Register a New Host With Load Balancer

Let's look first at registering the new host slave with the load balancer configuration in _domain.xml_.  Open this
file and go to the undertow configuration in the `load-balancer` profile.  Add a new `host` definition called
`remote-host3` within the `reverse-proxy` XML block.

.domain.xml reverse-proxy config
[source,xml]
----
<subsystem xmlns="urn:jboss:domain:undertow:3.0">
  ...
  <handlers>
      <reverse-proxy name="lb-handler">
         <host name="host1" outbound-socket-binding="remote-host1" scheme="ajp" path="/" instance-id="myroute1"/>
         <host name="host2" outbound-socket-binding="remote-host2" scheme="ajp" path="/" instance-id="myroute2"/>
         <host name="remote-host3" outbound-socket-binding="remote-host3" scheme="ajp" path="/" instance-id="myroute3"/>
      </reverse-proxy>
  </handlers>
  ...
</subsystem>
----

The `output-socket-binding` is a logical name pointing to a `socket-binding` configured later in the _domain.xml_ file.
the `instance-id` attribute must also be unique to the new host as this value is used by a cookie to enable sticky
sessions when load balancing.

Next go down to the `load-balancer-sockets` `socket-binding-group` and add the `outbound-socket-binding` for `remote-host3`.  This new
binding needs to point to the host and port of the new host.

.domain.xml outbound-socket-binding
[source,xml]
----
<socket-binding-group name="load-balancer-sockets" default-interface="public">
    ...
    <outbound-socket-binding name="remote-host1">
        <remote-destination host="localhost" port="8159"/>
    </outbound-socket-binding>
    <outbound-socket-binding name="remote-host2">
        <remote-destination host="localhost" port="8259"/>
    </outbound-socket-binding>
    <outbound-socket-binding name="remote-host3">
        <remote-destination host="192.168.0.5" port="8259"/>
    </outbound-socket-binding>
</socket-binding-group>
----

===== Master Bind Addresses

Next thing you'll have to do is to change the `public` and `management` bind addresses for the master host.  Either
edit the _domain.xml_ file as discussed in the <<fake/../../network/bind-address.adoc#_bind-address, Bind Addresses>> chapter
or specify these bind addresses on the command line as follows:

[source]
----
$ domain.sh --host-config=host-master.xml -Djboss.bind.address=192.168.0.2 -Djboss.bind.address.management=192.168.0.2
----

===== Host Slave Bind Addresses

Next you'll have to change the `public`, `management`, and domain controller bind addresses (`jboss.domain.master-address`).  Either edit the
_host-slave.xml_ file or specify them on the command line as follows:

[source]
----
$ domain.sh --host-config=host-slave.xml
     -Djboss.bind.address=192.168.0.5
      -Djboss.bind.address.management=192.168.0.5
       -Djboss.domain.master.address=192.168.0.2
----

The values of `jboss.bind.address` and `jboss.bind.addres.management` pertain to the host slave's IP address.
The value of `jboss.domain.master.address` need to be the IP address of the domain controller which is the management address
of the master host.

==== Configuring Other Load Balancers

See link:{{book.appserver.doc_base_url}}{{book.appserver.version}}{{book.appserver.loadbalancer_ref.link}}[{{book.appserver.loadbalancer_ref.name}}] in the _{{book.appserver.admindoc.name}}_ for information how to use other software-based load balancers.