fix: add the proxy-protocol option (#33276)

* fix: add the proxy-protocol-enabled option

closes: #10492

Signed-off-by: Steve Hawkins <shawkins@redhat.com>

* Update docs/guides/server/reverseproxy.adoc

Co-authored-by: Martin Bartoš <mabartos@redhat.com>
Signed-off-by: Steven Hawkins <shawkins@redhat.com>

---------

Signed-off-by: Steve Hawkins <shawkins@redhat.com>
Signed-off-by: Steven Hawkins <shawkins@redhat.com>
Co-authored-by: Martin Bartoš <mabartos@redhat.com>

docs/documentation/release_notes/topics/26_0_0.adoc

@@ -198,6 +198,10 @@ The `proxy-trusted-addresses` can be used when the `proxy-headers` option is set
 
 The `https-certificates-reload-period` option can be set to define the reloading period of key store, trust store, and certificate files referenced by https-* options. Use -1 to disable reloading. Defaults to 1h (one hour).
 
+= Option `proxy-protocol-enabled` added
+
+The `proxy-protocol-enabled` option controls whether the server should use the HA PROXY protocol when serving requests from behind a proxy. When set to true, the remote address returned will be the one from the actual connecting client.
+
 = Options to configure cache max-count added
 
 The `--cache-embedded-$\{CACHE_NAME}-max-count=` can be set to define an upper bound on the number of cache entries in the specified cache.

docs/guides/server/reverseproxy.adoc

@@ -134,6 +134,16 @@ For example:
 
 <@kc.start parameters="--proxy-headers forwarded --proxy-trusted-addresses=192.168.0.32,127.0.0.0/8"/> 
 
+== PROXY Protocol
+
+The `proxy-protocol-enabled` option controls whether the server should use the HA PROXY protocol when serving requests from behind a proxy. When set to true, the remote address returned will be the one from the actual connecting client.
+
+This is useful when running behind a compatible https passthrough proxy because the request headers cannot be manipulated.
+
+For example:
+
+<@kc.start parameters="--proxy-protocol-enabled true"/> 
+
 == Enabling client certificate lookup
 
 When the proxy is configured as a TLS termination proxy the client certificate information can be forwarded to the server through specific HTTP request headers and then used to authenticate

quarkus/config-api/src/main/java/org/keycloak/config/ProxyOptions.java

@@ -14,6 +14,12 @@ public class ProxyOptions {
             .description("The proxy headers that should be accepted by the server. Misconfiguration might leave the server exposed to security vulnerabilities. Takes precedence over the deprecated proxy option.")
             .build();
     
+    public static final Option<Boolean> PROXY_PROTOCOL_ENABLED = new OptionBuilder<>("proxy-protocol-enabled", Boolean.class)
+            .category(OptionCategory.PROXY)
+            .description("Whether the server should use the HA PROXY protocol when serving requests from behind a proxy. When set to true, the remote address returned will be the one from the actual connecting client.")
+            .defaultValue(Boolean.FALSE)
+            .build();
+
     public static final Option<Boolean> PROXY_FORWARDED_HOST = new OptionBuilder<>("proxy-forwarded-host", Boolean.class)
             .category(OptionCategory.PROXY)
             .defaultValue(Boolean.FALSE)

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/HealthPropertyMappers.java

@@ -13,7 +13,6 @@ final class HealthPropertyMappers {
         return new PropertyMapper[] {
                 fromOption(HealthOptions.HEALTH_ENABLED)
                         .to("quarkus.smallrye-health.extensions.enabled")
-                        .paramLabel(Boolean.TRUE + "|" + Boolean.FALSE)
                         .build()
         };
     }

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/HttpPropertyMappers.java

@@ -34,11 +34,9 @@ public final class HttpPropertyMappers {
                 fromOption(HttpOptions.HTTP_ENABLED)
                         .to("quarkus.http.insecure-requests")
                         .transformer(HttpPropertyMappers::getHttpEnabledTransformer)
-                        .paramLabel(Boolean.TRUE + "|" + Boolean.FALSE)
                         .build(),
                 fromOption(HttpOptions.HTTP_SERVER_ENABLED)
                         .to("quarkus.http.host-enabled")
-                        .paramLabel(Boolean.TRUE + "|" + Boolean.FALSE)
                         .build(),
                 fromOption(HttpOptions.HTTP_HOST)
                         .to("quarkus.http.host")

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/MetricsPropertyMappers.java

@@ -16,7 +16,6 @@ final class MetricsPropertyMappers {
         return new PropertyMapper[] {
                 fromOption(MetricsOptions.METRICS_ENABLED)
                         .to("quarkus.micrometer.enabled")
-                        .paramLabel(Boolean.TRUE + "|" + Boolean.FALSE)
                         .build()
         };
     }

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/ProxyPropertyMappers.java

@@ -21,6 +21,9 @@ final class ProxyPropertyMappers {
                         .transformer((v, c) -> proxyEnabled(null, v, c))
                         .paramLabel("headers")
                         .build(),
+                fromOption(ProxyOptions.PROXY_PROTOCOL_ENABLED)
+                        .to("quarkus.http.proxy.use-proxy-protocol")
+                        .build(),
                 fromOption(ProxyOptions.PROXY_FORWARDED_HOST)
                         .to("quarkus.http.proxy.enable-forwarded-host")
                         .mapFrom("proxy-headers")

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelp.approved.txt

@@ -267,6 +267,10 @@ Proxy:
                      The proxy headers that should be accepted by the server. Misconfiguration
                        might leave the server exposed to security vulnerabilities. Takes precedence
                        over the deprecated proxy option. Possible values are: forwarded, xforwarded.
+--proxy-protocol-enabled <true|false>
+                     Whether the server should use the HA PROXY protocol when serving requests from
+                       behind a proxy. When set to true, the remote address returned will be the
+                       one from the actual connecting client. Default: false.
 --proxy-trusted-addresses <trusted proxies>
                      A comma separated list of trusted proxy addresses. If set, then proxy headers
                        from other addresses will be ignored. By default all addresses are trusted.

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.approved.txt

@@ -302,6 +302,10 @@ Proxy:
                      The proxy headers that should be accepted by the server. Misconfiguration
                        might leave the server exposed to security vulnerabilities. Takes precedence
                        over the deprecated proxy option. Possible values are: forwarded, xforwarded.
+--proxy-protocol-enabled <true|false>
+                     Whether the server should use the HA PROXY protocol when serving requests from
+                       behind a proxy. When set to true, the remote address returned will be the
+                       one from the actual connecting client. Default: false.
 --proxy-trusted-addresses <trusted proxies>
                      A comma separated list of trusted proxy addresses. If set, then proxy headers
                        from other addresses will be ignored. By default all addresses are trusted.

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelp.approved.txt

@@ -268,6 +268,10 @@ Proxy:
                      The proxy headers that should be accepted by the server. Misconfiguration
                        might leave the server exposed to security vulnerabilities. Takes precedence
                        over the deprecated proxy option. Possible values are: forwarded, xforwarded.
+--proxy-protocol-enabled <true|false>
+                     Whether the server should use the HA PROXY protocol when serving requests from
+                       behind a proxy. When set to true, the remote address returned will be the
+                       one from the actual connecting client. Default: false.
 --proxy-trusted-addresses <trusted proxies>
                      A comma separated list of trusted proxy addresses. If set, then proxy headers
                        from other addresses will be ignored. By default all addresses are trusted.

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.approved.txt

@@ -303,6 +303,10 @@ Proxy:
                      The proxy headers that should be accepted by the server. Misconfiguration
                        might leave the server exposed to security vulnerabilities. Takes precedence
                        over the deprecated proxy option. Possible values are: forwarded, xforwarded.
+--proxy-protocol-enabled <true|false>
+                     Whether the server should use the HA PROXY protocol when serving requests from
+                       behind a proxy. When set to true, the remote address returned will be the
+                       one from the actual connecting client. Default: false.
 --proxy-trusted-addresses <trusted proxies>
                      A comma separated list of trusted proxy addresses. If set, then proxy headers
                        from other addresses will be ignored. By default all addresses are trusted.

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelp.approved.txt

@@ -220,6 +220,10 @@ Proxy:
                      The proxy headers that should be accepted by the server. Misconfiguration
                        might leave the server exposed to security vulnerabilities. Takes precedence
                        over the deprecated proxy option. Possible values are: forwarded, xforwarded.
+--proxy-protocol-enabled <true|false>
+                     Whether the server should use the HA PROXY protocol when serving requests from
+                       behind a proxy. When set to true, the remote address returned will be the
+                       one from the actual connecting client. Default: false.
 --proxy-trusted-addresses <trusted proxies>
                      A comma separated list of trusted proxy addresses. If set, then proxy headers
                        from other addresses will be ignored. By default all addresses are trusted.

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.approved.txt

@@ -255,6 +255,10 @@ Proxy:
                      The proxy headers that should be accepted by the server. Misconfiguration
                        might leave the server exposed to security vulnerabilities. Takes precedence
                        over the deprecated proxy option. Possible values are: forwarded, xforwarded.
+--proxy-protocol-enabled <true|false>
+                     Whether the server should use the HA PROXY protocol when serving requests from
+                       behind a proxy. When set to true, the remote address returned will be the
+                       one from the actual connecting client. Default: false.
 --proxy-trusted-addresses <trusted proxies>
                      A comma separated list of trusted proxy addresses. If set, then proxy headers
                        from other addresses will be ignored. By default all addresses are trusted.