diff --git a/docbook/auth-server-docs/reference/en/en-US/modules/clustering.xml b/docbook/auth-server-docs/reference/en/en-US/modules/clustering.xml
index fc9cc558c8..5e16788a76 100755
--- a/docbook/auth-server-docs/reference/en/en-US/modules/clustering.xml
+++ b/docbook/auth-server-docs/reference/en/en-US/modules/clustering.xml
@@ -47,6 +47,11 @@
Start in HA mode
+
+
+ Loadbalancer (optional step)
+
+
@@ -192,6 +197,20 @@
+
+ Loadbalancer setup
+
+ This is optional step, however in production, when you have more Keycloak nodes in cluster, you usually want to "hide" them behind frontent loadbalancer server, which will forward the
+ requests to the "backend" keycloak nodes. Consult the documentation of your loadbalancer (For example Mod cluster )
+ for how to configure this.
+
+
+ But regardless of loadbalancer implementation used, it is important that you make sure the web server sets the X-Forwarded-For and
+ X-Forwarded-Proto headers on the requests made to Keycloak properly. This is described in details in Reverse proxy
+ section.
+
+
+
Troubleshooting
diff --git a/docbook/auth-server-docs/reference/en/en-US/modules/security-vulnerabilities.xml b/docbook/auth-server-docs/reference/en/en-US/modules/security-vulnerabilities.xml
index 9a9b1d84c1..35ba499b69 100755
--- a/docbook/auth-server-docs/reference/en/en-US/modules/security-vulnerabilities.xml
+++ b/docbook/auth-server-docs/reference/en/en-US/modules/security-vulnerabilities.xml
@@ -129,7 +129,7 @@
applications register as specific a URI pattern as possible to mitigate open redirector attacks.
-
+ Password guess: brute force attacks
A brute force attack happens when an attacker is trying to guess a user's password. Keycloak has some
diff --git a/docbook/auth-server-docs/reference/en/en-US/modules/server-installation.xml b/docbook/auth-server-docs/reference/en/en-US/modules/server-installation.xml
index 00583643c1..4b0e19ff3c 100755
--- a/docbook/auth-server-docs/reference/en/en-US/modules/server-installation.xml
+++ b/docbook/auth-server-docs/reference/en/en-US/modules/server-installation.xml
@@ -516,7 +516,7 @@ bin/add-user-keycloak.[sh|bat] -r master -u -p
otherwise cacerts file that comes with java is used.
- Truststore is used when connecting securely to identity brokers, LDAP identity providers, when sending emails,
+ Truststore is used when connecting securely to identity brokers, LDAP federation providers, when sending emails,
and for backchannel communication with client applications.
Some of these facilities may - in case when no trusted certificate is found in your configured truststore -
@@ -785,7 +785,7 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat
]]>
- Check the Wildfly Undertow documentation for more information on fine tuning the socket connections.
+ Check the Wildfly Undertow documentation for more information on fine tuning the socket connections.
@@ -795,9 +795,12 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat
Follow the documentation for your web server to enable SSL and configure reverse proxy for Keycloak.
It is important that you make sure the web server sets the X-Forwarded-For and
- X-Forwarded-Proto headers on the requests made to Keycloak. Next you need to enable
- proxy-address-forwarding on the Keycloak http connector. Assuming that your reverse
- proxy doesn't use port 8443 for SSL you also need to configure what port http traffic is redirected to.
+ X-Forwarded-Proto headers on the requests made to Keycloak and you enable
+ proxy-address-forwarding on the Keycloak http connector. This is described in next section, so
+ here we will focus just on SSL setup.
+
+
+ Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port http traffic is redirected to.
@@ -808,12 +811,11 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat
- First add proxy-address-forwarding and redirect-socket to
+ First add redirect-socket to
the http-listener element:
...
-
+
...
]]>
@@ -830,13 +832,115 @@ $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificat
]]>
- Check the WildFly documentation for more information.
+ Check the WildFly documentation for more information.
+
+ Configure reverse proxy for address forwarding
+
+ Keycloak has some functionalities (for example Events or Brute Force protector)
+ that relies on the fact, that remote address of the HTTP connection is the real IP address of the client machine. This may be a bit tricky when you have setup
+ with reverse proxy or loadbalancer.
+
+
+ Assume you have setup when users send requests to the "Frontend" server (reverse proxy), which then forwards them to the
+ "backend" server (Keycloak) on private network. Then with default setup of Wildfly Undertow subsystem, Keycloak will see request.getRemoteAddress() to be
+ resolved to the IP address of reverse proxy instead of real IP of client.
+
+
+ To address this issue and see the real IP address of client, you need 2 things:
+
+
+ Configure your reverse proxy (loadbalancer) to properly set X-Forwarded-For and X-Forwarded-Proto HTTP headers.
+
+
+ Configure Wildfly undertow subsystem on Keycloak server's side to read the client's IP address from X-Forwarded-For header.
+
+
+ More details for setup both things.
+
+
+ Configure your reverse proxy to set X-Forwarded-For
+
+ Consult the documentation of your reverse proxy implementation on how to do it.
+
+
+ Note that when your reverse proxy receives requests from the users on public network, you also need to ensure that X-Forwarded-For
+ is always overwritten by proxy with the IP address of client machine. If it's not overwritten, but just forwarded, the
+ "evil" user can manually set the X-Forwarded-For header to the false IP address to trick Keycloak.
+
+
+ For example imagine that evil user connects from IP address 20.20.20.20 but he manually sets the X-Forwarded-For header to
+ value 30.30.30.30. If reverse proxy "forwards" the header, it will append the old value set by evil user with the IP address user connected from.
+ So X-Forwarded-For header will be incorrectly set to 30.30.30.30 , 20.20.20.20. Then Keycloak will see incorrect IP
+ address 30.30.30.30. So in this case, reverse proxy must overwrite the old value of header and just set the real IP
+ of the user machine to 20.20.20.20. On the other hand, when you have more reverse proxies chained together, you need to configure
+ "overwriting" just for the first proxy in the chain.
+
+
+ Some example setups:
+
+
+ user (IP address: 20.20.20.20) -> load balancer (IP Address: 30.30.30.30 ) -> Keycloak
+
+
+ For this setup, loadbalancer receives the IP from the end user, so it must overwrite the header. So Keycloak will correctly see
+ X-Forwarded-For: 20.20.20.20 .
+
+
+
+
+ internet (IP address: 20.20.20.20) -> reverse proxy (IP Address: 30.30.30.30 ) -> load balancer (IP Address: 40.40.40.40 ) -> keycloak
+
+
+ For this setup, just the first reverse proxy is supposed to overwrite X-Forwarded-For but second (load balancer) should just forwards it.
+ So Keycloak will correctly see X-Forwarded-For: 20.20.20.20,30.30.30.30, hence in the second step, it will be able to correctly see
+ client's remote IP address 20.20.20.20.
+
+
+
+
+
+
+
+ Configure Wildfly undertow subsystem
+
+ This is needed, so the wildfly undertow subsystem will read the client's IP address from the X-Forwarded-For header rather than from the IP of network packet, which
+ came from loadbalancer and hence it's set to the IP of loadbalancer.
+
+
+ If your proxy sends requests to the HTTP connector, it can be configured easily by add attribute proxy-address-forwarding to the
+ http-listener subelement of undertow subsystem.
+ For example:
+
+]]>
+
+
+ If you use AJP connector, which is common setup for loadbalancers, the proxy-address-forwarding is not available, hence you need to do slightly more configurations.
+ First add filter subelement of filters element with the value like this:
+
+]]>
+ Then reference it from the host element:
+
+]]>
+ If you want to check address is correctly set, you can enable events and verify the IP address really points to the IP address of client machine.
+
+
+ Check the WildFly documentation for more information.
+
+
+
+