240 lines
11 KiB
Text
240 lines
11 KiB
Text
[[_setting-up-a-load-balancer-or-proxy]]
|
|
=== 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 {project_name} deployment. It also covers configuring the built-in load balancer that
|
|
was <<_clustered-domain-example, Clustered Domain Example>>.
|
|
|
|
The following diagram illustrates the use of a load balancer. In this example, the load balancer serves as a reverse proxy between three clients and a cluster of three {project_name} servers.
|
|
|
|
[[load-balancer-diagram]]
|
|
.Example Load Balancer Diagram
|
|
image:{project_images}/load_balancer.png[]
|
|
|
|
==== Identifying client IP addresses
|
|
|
|
A few features in {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. Examples include:
|
|
|
|
* Event logs - a failed login attempt would be logged with the wrong source IP address
|
|
* SSL required - if the SSL required is set to external (the default) it should require SSL for all external requests
|
|
* Authentication flows - a custom authentication flow that uses the IP address to for example show OTP only for external requests
|
|
* Dynamic Client Registration
|
|
|
|
This can be problematic when you have a reverse proxy or loadbalancer in front of your {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 {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 {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-Forwarded-For` header is set by your proxy. If your proxy isn't configured correctly, then _rogue_ clients can set this header themselves and trick {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 {project_name} side of things.
|
|
If your proxy is forwarding requests via the HTTP protocol, then you need to configure {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
|
|
<<_operating-mode, operating mode>>) and look for the `{subsystem_undertow_xml_urn}` XML block.
|
|
|
|
.`X-Forwarded-For` HTTP Config
|
|
[source,xml,subs="attributes+"]
|
|
----
|
|
<subsystem xmlns="{subsystem_undertow_xml_urn}">
|
|
<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,subs="attributes+"]
|
|
----
|
|
<subsystem xmlns="{subsystem_undertow_xml_urn}">
|
|
<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>
|
|
----
|
|
|
|
==== Enabling HTTPS/SSL with a reverse proxy
|
|
|
|
Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure to what port the HTTPS traffic is redirected.
|
|
[source,xml,subs="attributes+"]
|
|
----
|
|
<subsystem xmlns="{subsystem_undertow_xml_urn}">
|
|
...
|
|
<http-listener name="default" socket-binding="http"
|
|
proxy-address-forwarding="true" redirect-socket="proxy-https"/>
|
|
...
|
|
</subsystem>
|
|
----
|
|
|
|
.Procedure
|
|
|
|
. 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.
|
|
|
|
. 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>
|
|
----
|
|
|
|
==== Verifying the configuration
|
|
|
|
You can verify the reverse proxy or load balancer configuration
|
|
|
|
.Procedure
|
|
|
|
. Open 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 {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 {project_name} is using the correct endpoint.
|
|
|
|
. Verify that {project_name} sees the correct source IP address for requests.
|
|
+
|
|
To 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
|
|
<<_clustered-domain-example, Clustered Domain Example>>.
|
|
|
|
The <<_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
|
|
|
|
.Procedure
|
|
|
|
. Open _domain.xml_ so you can registering the new host slave with the load balancer configuration.
|
|
|
|
. 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,subs="attributes+"]
|
|
----
|
|
<subsystem xmlns="{subsystem_undertow_xml_urn}">
|
|
...
|
|
<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.
|
|
|
|
. 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 <<_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.address.management` pertain to the host slave's IP address.
|
|
The value of `jboss.domain.master.address` needs to be the IP address of the domain controller, which is the management address of the master host.
|
|
|
|
[role="_additional-resources"]
|
|
.Additional resources
|
|
|
|
* See link:{appserver_loadbalancer_link}[the load balancing] section in the _{appserver_loadbalancer_name}_ for information how to use other software-based load balancers.
|
|
|