From 71247538eea1296f3b4a3010a1a94e642616e34f Mon Sep 17 00:00:00 2001 From: mposolda Date: Thu, 28 Apr 2016 13:01:32 +0200 Subject: [PATCH] KEYCLOAK-2903 Document proxy-address-forwarding with reverse proxy/loadbalancer setup --- .../reference/en/en-US/modules/clustering.xml | 19 +++ .../modules/security-vulnerabilities.xml | 2 +- .../en/en-US/modules/server-installation.xml | 122 ++++++++++++++++-- 3 files changed, 133 insertions(+), 10 deletions(-) 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. + +
+
+