From 8cfe8b1411fa560a72e83a19002e2d9c06ec092b Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Mon, 15 May 2023 17:44:47 +0200 Subject: [PATCH] Update the docs on passthrough proxy (#20072) Closes #20070 --- docs/documentation/release_notes/topics/22_0_0.adoc | 8 +++++++- .../upgrading/topics/keycloak/changes-22_0_0.adoc | 10 +++++++++- docs/guides/server/reverseproxy.adoc | 8 ++++---- .../configuration/mappers/ProxyPropertyMappers.java | 2 +- .../quarkus/src/main/content/conf/keycloak.conf | 3 ++- 5 files changed, 23 insertions(+), 8 deletions(-) diff --git a/docs/documentation/release_notes/topics/22_0_0.adoc b/docs/documentation/release_notes/topics/22_0_0.adoc index b4e58f3c31..5144276a9e 100644 --- a/docs/documentation/release_notes/topics/22_0_0.adoc +++ b/docs/documentation/release_notes/topics/22_0_0.adoc @@ -48,4 +48,10 @@ See the migration guide for more details. The Admin Console (and soon also the new Account Console) works slightly different than the rest of Keycloak in regards to how keys for internationalized messages are parsed. This is due to the fact that it uses the https://www.i18next.com/[i18next] library for internationalization. Therefore when defining custom messages for the Admin Console under "Realm Settings" ➡ "Localization" best practices for i18next must be taken into account. Specifically, when defining a message for the Admin Console it is it important to specify a https://www.i18next.com/principles/namespaces[namespace] in the key of your message. -For example, let's assume we want to overwrite the https://github.com/keycloak/keycloak/blob/025778fe9c745316f80b53fe3052aeb314e868ef/js/apps/admin-ui/public/locales/en/dashboard.json#L3[`welcome`] message shown to the user when a new realm has been created. This message is located in the `dashboard` namespace, same as the name of the original file that holds the messages (`dashboard.json`). If we wanted to overwrite this message we'll have to use the namespace as a prefix followed by the key of the message separated by a colon, in this case it would become `dashboard:welcome`. \ No newline at end of file +For example, let's assume we want to overwrite the https://github.com/keycloak/keycloak/blob/025778fe9c745316f80b53fe3052aeb314e868ef/js/apps/admin-ui/public/locales/en/dashboard.json#L3[`welcome`] message shown to the user when a new realm has been created. This message is located in the `dashboard` namespace, same as the name of the original file that holds the messages (`dashboard.json`). If we wanted to overwrite this message we'll have to use the namespace as a prefix followed by the key of the message separated by a colon, in this case it would become `dashboard:welcome`. + += Passthrough proxy mode changes + +Installations which use Keycloak's `--proxy` configuration setting with mode *passthrough* should review the documentation as the behavior of this mode has changed. + +See the migration guide for more details. diff --git a/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc b/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc index a571d0c89c..ea0c569d5d 100644 --- a/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc +++ b/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc @@ -176,4 +176,12 @@ The new artifact with Java EE support is `org.keycloak:keycloak-admin-client-jee keycloak-admin-client-jee 22.0.0 ----- \ No newline at end of file +---- + += Passthrough proxy mode changes + +Keycloak's proxy configuration setting for mode *passthrough* no longer parses HTTP forwarding headers in the request, as when a proxy forwards an HTTPS connection in passthrough mode, a proxy is unable to add, remove or update HTTP headers. + +Installations that want the HTTP headers in the client's request to be parsed should use the **edge** or **reencrypt** setting. + +See https://www.keycloak.org/server/reverseproxy[Using a reverse proxy] for details. diff --git a/docs/guides/server/reverseproxy.adoc b/docs/guides/server/reverseproxy.adoc index e1cbfe0ed5..9e00c229d5 100644 --- a/docs/guides/server/reverseproxy.adoc +++ b/docs/guides/server/reverseproxy.adoc @@ -21,9 +21,8 @@ reencrypt:: Requires communication through HTTPS between the proxy and Keycloak. This mode is suitable for deployments where internal communication between the reverse proxy and Keycloak should also be protected. Different keys and certificates are used on the reverse proxy as well as on Keycloak. -passthrough:: Enables communication through HTTP or HTTPS between the proxy and Keycloak. -This mode is suitable for deployments where the reverse proxy is not terminating TLS. -The proxy instead is forwarding requests to the Keycloak server so that secure connections between the server and clients are based on the keys and certificates used by the Keycloak server. +passthrough:: The proxy forwards the HTTPS connection to Keycloak without terminating TLS. +The secure connections between the server and clients are based on the keys and certificates used by the Keycloak server. == Configure the proxy mode in Keycloak To select the proxy mode, enter this command: @@ -31,9 +30,10 @@ To select the proxy mode, enter this command: <@kc.start parameters="--proxy "/> == Configure the reverse proxy + Some Keycloak features rely on the assumption that the remote address of the HTTP request connecting to Keycloak is the real IP address of the clients machine. -When you have a reverse proxy or a load balancer in front of Keycloak, please make sure your reverse proxy is overriding the following headers: +When in **edge** or **reencrypt** proxy mode, Keycloak will parse the following headers and expects the reverse proxy to set them: * `Forwarded` as per https://www.rfc-editor.org/rfc/rfc7239.html[RFC7239] * Non-standard `X-Forwarded` diff --git a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ProxyPropertyMappers.java b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ProxyPropertyMappers.java index b07c984d45..1698df33cb 100644 --- a/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ProxyPropertyMappers.java +++ b/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ProxyPropertyMappers.java @@ -45,10 +45,10 @@ final class ProxyPropertyMappers { switch (mode) { case "none": + case "passthrough": return of(Boolean.FALSE.toString()); case "edge": case "reencrypt": - case "passthrough": return of(Boolean.TRUE.toString()); default: addInitializationException(Messages.invalidProxyMode(mode)); diff --git a/testsuite/integration-arquillian/servers/auth-server/quarkus/src/main/content/conf/keycloak.conf b/testsuite/integration-arquillian/servers/auth-server/quarkus/src/main/content/conf/keycloak.conf index 8757aa13a6..9f391977e3 100644 --- a/testsuite/integration-arquillian/servers/auth-server/quarkus/src/main/content/conf/keycloak.conf +++ b/testsuite/integration-arquillian/servers/auth-server/quarkus/src/main/content/conf/keycloak.conf @@ -18,7 +18,8 @@ https-trust-store-password=secret https-client-auth=REQUEST # Proxy -proxy=passthrough +# Using any proxy setting which evaluates the forward proxy header +proxy=reencrypt # Hostname Provider spi-hostname-default-frontend-url = ${keycloak.frontendUrl:}