Update the docs on passthrough proxy (#20072)

Closes #20070

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`.
+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.

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
     <artifactId>keycloak-admin-client-jee</artifactId>
     <version>22.0.0</version>
 </dependency>
-----
+----
+
+= 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.

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 <mode>"/>
 
 == 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`

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));

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:}