bin/kc.[sh|bat] start --proxy-protocol-enabled trueDistributed environments frequently require the use of a reverse proxy. Keycloak offers several options to securely integrate with such environments.
When deploying Keycloak behind a reverse proxy, there are three common approaches for handling TLS connections between clients, the proxy, and Keycloak: re-encrypt, edge termination and passthrough.
For re-encrypt, the reverse proxy terminates the client TLS connection and establishes a TLS connection to Keycloak.
The proxy can inspect and modify HTTP headers (such as Forwarded or X-Forwarded-*) before re-encrypting the traffic to the backend.
The proxy and Keycloak use independent TLS certificates: the proxy presents its own certificate to clients, while Keycloak uses a separate certificate for backend communication.
Configure --proxy-headers so that Keycloak parses the forwarded headers set by the proxy, including the real client IP address.
The edge termination is similar to re-encrypt as the proxy terminates the TLS connection, but the connection between the proxy and Keycloak is then unencrypted. As edge termination is generally considered less secure than re-encrypt, this guide focuses on re-encrypt instead.
With passthrough, the reverse proxy forwards the raw TLS connection directly to Keycloak without terminating it.
The TLS handshake occurs between the client and Keycloak, so the proxy cannot inspect or modify HTTP traffic.
Do not set --proxy-headers because the proxy cannot inject forwarded headers into the encrypted traffic.
Enable the PROXY protocol (--proxy-protocol-enabled=true) so that Keycloak can see the real client IP address.
The following table compares different aspects of the re-encrypt and passthrough proxy configurations.
| Aspect | Re-encrypt | Passthrough |
|---|---|---|
TLS between client and proxy |
Yes |
Yes (end-to-end) |
TLS between proxy and Keycloak |
Yes |
N/A (direct tunnel) |
Proxy can modify HTTP headers |
Yes |
No |
Proxy can filter URL paths |
Yes |
No |
Keycloak manages TLS certificates |
Yes |
Yes |
Client certificate (X.509) forwarding |
Via HTTP headers added by the proxy |
Native (no header needed) |
Re-encrypt is the most common choice for production deployments. It allows the proxy to set forwarded headers, filter URL paths, and apply HTTP-level policies while maintaining TLS encryption on both sides of the proxy. The proxy and Keycloak can use different TLS certificates, giving you flexibility in certificate management. Because the proxy can inspect HTTP traffic, it can also pool backend connections, cache static resources, and use cookie-based session affinity.
Passthrough provides true end-to-end encryption without TLS termination at the proxy. It is the recommended mode when using X.509 client certificate authentication because the client certificate reaches Keycloak directly without being forwarded through an HTTP header, which eliminates the risk of forged client certificate headers. However, because the proxy cannot modify HTTP traffic, it cannot set forwarded headers or filter URL paths. This mode also requires Keycloak to present a certificate that covers all its externally visible hostnames, which can complicate certificate management.
When using re-encrypt:
Restrict network access so that Keycloak accepts connections only from the proxy. Without this restriction, clients could bypass the proxy and send forged forwarded headers directly to Keycloak.
Set --proxy-trusted-addresses to the IP addresses of your proxy to ensure forwarded headers are accepted only from these IP addresses. Note that this is only weak protection because IP addresses can be spoofed.
Ensure the proxy overwrites (not just appends to) forwarded headers to prevent clients from injecting false values.
When using passthrough:
Restrict network access so that Keycloak accepts connections only from the proxy.
Forwarded headers are not applicable because the proxy cannot modify the encrypted traffic.
Enable the PROXY protocol (--proxy-protocol-enabled=true) to see the real client IP address.
Note that the PROXY protocol is not compatible with the --proxy-headers option.
The PROXY protocol header that the proxy adds to convey the client IP address is neither encrypted nor signed. Therefore, it can be spoofed, tampered with, or leaked. Mitigate this risk, for example, by restricting network access.
Allow a longer --shutdown-delay (for example, 10–30 seconds) to give keepalive connections time to drain during shutdown, since the proxy cannot signal a connection close at the HTTP connection level.
Due to HTTP/2 connection coalescing, do not configure Keycloak to be the proxy’s default backend when Keycloak is using a wildcard certificate and that certificate is shared among several services behind the proxy. In this configuration Keycloak will not be able to distinguish between misdirected requests and those sent by default - when no SNI information is sent or SNI does not match any backend.
If private backchannel access to Keycloak is requested, using a proxy might be challenging:
When the PROXY protocol is used for TLS passthrough, clients cannot connect directly to Keycloak without the PROXY protocol. Any direct connection would also allow spoofing of IP source addresses.
When using TLS re-encrypt, it might be impossible to restrict proxy traffic to specific source IP addresses when the proxy’s IP addresses are dynamic. Not restricting the proxy traffic would allow clients to spoof proxy headers.
In these setups, it might be better to stick with a single proxy and no backchannel access, or to deploy an internal proxy in addition to the external proxy.
When deploying a second proxy, there are additional considerations:
Restrict network access so that Keycloak accepts connections only from the two proxies, for example, by adding network filtering.
Both proxies need to use the same mode. Either both need to use TLS passthrough, or both need to use TLS re-encrypt.
If using TLS passthrough mode, both proxies can forward requests using the PROXY protocol. As Keycloak presents a single TLS certificate for both paths, it needs to include a subject alternative name (SAN) for the second path so callers can validate TLS on both paths. Note that this SAN will be visible on both paths. While this is not a technical problem, it still leaks an internal hostname on the public path.
If using TLS re-encrypt mode, both proxies would filter incoming HTTP headers, and add trusted HTTP headers.
Keycloak runs on the following ports by default:
8443 (8080 when you enable HTTP explicitly by --http-enabled=true)
9000
The port 8443 (or 8080 if HTTP is enabled) is used for the Admin UI, Account Console, SAML and OIDC endpoints, and the Admin REST API as described in the Configuring the hostname (v2) guide.
The port 9000 is used for management, which includes endpoints for health checks and metrics as described in the Configuring the Management Interface guide.
You only need to proxy port 8443 (or 8080) even when you use different hostnames for frontend/backend and administration as described in Configuring Keycloak for production.
You should not proxy port 9000 because health checks and metrics use that port directly, and you do not want to expose this information to external callers.
In TLS passthrough mode, the proxy forwards the raw TLS connection to Keycloak without terminating it.
Because the proxy cannot inspect or modify HTTP traffic, it cannot set or overwrite HTTP headers such as Forwarded or X-Forwarded-*.
|
Do not set |
Without forwarded headers, the only way for Keycloak to see the real client IP address is through the PROXY protocol, which is strongly recommended for TLS passthrough deployments.
The PROXY protocol allows the proxy to prepend the original client connection information (such as the source IP address) to the TCP stream before forwarding it to Keycloak. This happens outside of the TLS-encrypted channel, so it works even though the proxy cannot modify HTTP traffic.
Enable it in Keycloak with the --proxy-protocol-enabled option:
bin/kc.[sh|bat] start --proxy-protocol-enabled trueThe proxy must also be configured to send the PROXY protocol header.
Most proxies support both version 1 (text-based) and version 2 (binary).
Consult your proxy’s documentation for the specific configuration directive (for example, send-proxy-v2 in HAProxy).
The --proxy-protocol-enabled option and the --proxy-headers option are mutually exclusive.
Setting both will result in a configuration error.
|
In TLS re-encrypt mode, the proxy terminates the client TLS connection and establishes a new TLS connection to Keycloak. Because the proxy can inspect and modify HTTP traffic, additional configuration options are available, such as forwarded headers, path filtering, sticky sessions, and client certificate forwarding.
Keycloak parses the reverse proxy headers based on the proxy-headers option, which accepts several values:
forwarded enables parsing of the Forwarded header as per RFC 7239.
xforwarded enables parsing of non-standard X-Forwarded-* headers, such as X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, and X-Forwarded-Prefix.
If you are using a reverse proxy for anything other than TLS passthrough and do not set the proxy-headers option, then by default you will see 403 Forbidden responses to requests via the proxy that perform origin checking.
|
For example:
bin/kc.[sh|bat] start --proxy-headers forwarded
If either forwarded or xforwarded is selected, make sure your reverse proxy properly sets and overwrites the Forwarded or X-Forwarded-* headers respectively. To set these headers, consult the documentation for your reverse proxy. Do not use forwarded or xforwarded with TLS passthrough. Misconfiguration will leave Keycloak exposed to security vulnerabilities.
|
Take extra precautions to ensure that the client address is properly set by your reverse proxy via the Forwarded or X-Forwarded-For headers.
If these headers are incorrectly configured, rogue clients can inject false values and trick Keycloak into thinking the client is connecting from a different IP address than the actual one.
This precaution is especially critical if you do any deny or allow listing of IP addresses.
When using the xforwarded setting, the X-Forwarded-Port takes precedence over any port included in the X-Forwarded-Host.
|
If the TLS connection is terminated at the reverse proxy (edge termination), enabling HTTP through the http-enabled setting is required.
|
To ensure that proxy headers are used only from proxies you trust, set the proxy-trusted-addresses option to a comma-separated list of IP addresses (IPv4 or IPv6) or Classless Inter-Domain Routing (CIDR) notations.
For example:
bin/kc.[sh|bat] start --proxy-headers forwarded --proxy-trusted-addresses=192.168.0.32,127.0.0.0/8When using TLS re-encrypt, the proxy can inspect and modify HTTP traffic. Use this capability to prevent external clients from injecting headers that affect identity resolution, access control, or observability.
| The following assumes that there is only a single proxy layer in front of Keycloak, and that it is not receiving traffic from another trusted proxy layer with trusted headers. |
Configure the proxy to apply the following rules to incoming requests before forwarding them to Keycloak:
Overwrite Forwarded and X-Forwarded-* headers with the proxy’s own values rather than removing them, because Keycloak relies on these headers when --proxy-headers is configured.
Strip all other headers listed below entirely.
Depending on your security setup, you might want to allow some of the tracing headers through — either as-is or after sanitizing their values — for requests from trusted callers. This assessment depends on your trust boundaries and security trade-offs and is out of scope for this guide.
| Header(s) | Category | Risk if not filtered |
|---|---|---|
|
Proxy identity |
Clients can spoof their IP address, protocol, or host, affecting access control and audit logging. Overwrite these headers rather than stripping them. |
|
Proxy identity |
Variant of |
|
Proxy identity |
Trusted by some applications for rate limiting and audit logging. Can be spoofed to bypass IP-based restrictions. |
|
Proxy identity |
Used by authentication sub-request mechanisms in some proxies. Can be spoofed to manipulate path-based authorization decisions. |
|
Proxy identity |
Injected by some OAuth2 proxies. Can be spoofed to inject forged access tokens. |
|
Distributed tracing |
W3C Trace Context headers. External injection allows attackers to correlate requests in the tracing backend and map internal service dependencies. |
|
Distributed tracing |
W3C Baggage header. Can inject arbitrary key-value pairs into the trace context propagated to downstream services. |
|
Distributed tracing |
Zipkin B3 propagation headers. External injection inflates observability costs and enables cross-service correlation. |
|
Distributed tracing |
Jaeger propagation header (deprecated in favor of W3C Trace Context). Same risks as other tracing headers. |
|
Distributed tracing |
OpenTracing propagation header (deprecated in favor of W3C Trace Context). Same risks as other tracing headers. |
When using a reverse proxy, Keycloak only requires certain paths to be exposed. The following table shows the recommended paths to expose.
| Keycloak Path | Reverse Proxy Path | Exposed | Reason |
|---|---|---|---|
/ |
- |
No |
When exposing all paths, admin paths are exposed unnecessarily. |
/admin/ |
- |
Only internally |
Exposed admin paths lead to an unnecessary attack vector. |
/realms/ |
/realms/ |
Yes |
This path is needed to work correctly, for example, for OIDC endpoints. |
/realms/master/ |
/realms/master/ |
Only internally |
Assuming the administrative realm is called |
/resources/ |
/resources/ |
Yes |
This path is needed to serve assets correctly. It may be served from a CDN instead of the Keycloak path. |
/.well-known/ |
/.well-known/ |
Yes |
This path is needed to resolve Authorization Server Metadata and other information via RFC 8414. |
/metrics |
- |
No |
Exposed metrics lead to an unnecessary attack vector. |
/health |
- |
No |
Exposed health checks lead to an unnecessary attack vector. |
/lb-check |
/lb-check |
Yes |
Endpoint to be used for an external load balancer to check the availability of a Keycloak cluster. |
We assume you run Keycloak on the root path / on your reverse proxy/gateway’s public API.
If not, prefix the path with your desired one.
If you configured an http-relative-path on the server, proceed as follows to use discovery with RFC 8414: Configure a reverse proxy to map the /.well-known/ path without the prefix to the path with the prefix on the server.
|
The lb-check endpoint is only available when the stateless or the multi-site feature is enabled.
It is intended for external load balancers when you do not want to expose the management interface and its /health endpoints publicly.
This is a non-blocking endpoint and should remain responsive under high load, so the load balancer does not remove a healthy cluster from rotation during transient overload.
As a security best practice, restrict access to the authentication protocol endpoints of the administrative realm from public IP addresses.
The following description assumes Keycloak’s default settings and that this realm is called master.
To do that, do not expose the path /realms/master/ to the public internet.
Depending on your topology, you can combine this with serving the Admin UI and Admin API on a dedicated hostname and port. See Configuring the hostname (v2) for details.
By default, Keycloak is exposed through the root context path (/).
If the proxy uses a different context path than Keycloak, one of the following must be done:
Use a simple hostname for the hostname option, xforwarded for the proxy-headers option, and have the proxy set the X-Forwarded-Prefix header.
Use a full URL for the hostname option including the proxy context path, for example using --hostname=https://my.keycloak.org/auth if Keycloak is exposed through the reverse proxy on /auth.
Change the context path of Keycloak itself to match the context path for the reverse proxy using the http-relative-path option.
For more details on exposing Keycloak on a different hostname or context path, including the Administration REST API and Console, see Configuring the hostname (v2).
In previous versions of Keycloak, sticky sessions could improve performance by routing all requests for a browser session to the same backend node, avoiding remote cache lookups for session data.
Keycloak appended the owning node’s route to the AUTH_SESSION_ID cookie (for example, 123.node2) so that the load balancer could parse it for routing decisions.
Since the optimizations in 26.6, sticky sessions no longer bring a significant benefit given the complex setup on the proxy side to get this working. Authentication sessions are created on the node where the browser starts the session, and while a session may move to another node on a subsequent request, the overhead is low. Most interactions such as backchannel calls and token refreshes do not use cookies and are distributed across nodes regardless. The recommendation is to aim for an even distribution of load across Keycloak nodes instead of using sticky sessions.
The options spi-sticky-session-encoder--infinispan--should-attach-route and spi-sticky-session-encoder--remote--should-attach-route are deprecated since Keycloak 26.8 and will be removed in a future release.
To suppress the deprecation warning at startup, set those SPI options to false:
bin/kc.[sh|bat] start --spi-sticky-session-encoder--infinispan--should-attach-route=falseWhen 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 clients. You can configure how the server retrieves client certificate information depending on the proxy you are using.
|
Client certificate lookup via a proxy header for X.509 authentication is considered security-sensitive. If misconfigured, a forged client certificate header can be used for authentication. Extra precautions need to be taken to ensure that the client certificate information can be trusted when passed via a proxy header.
|
The server supports some of the most common TLS termination proxies:
| Provider | Proxies |
|---|---|
apache |
Apache HTTP Server |
haproxy |
HAProxy |
nginx |
NGINX |
traefik |
Traefik (PassTLSClientCert middleware with |
rfc9440 |
Proxies compliant with RFC 9440 |
envoy |
Envoy |
To configure how client certificates are retrieved from the requests, you need to:
bin/kc.[sh|bat] build --spi-x509cert-lookup--provider=<provider>bin/kc.[sh|bat] start --spi-x509cert-lookup--<provider>--ssl-client-cert=SSL_CLIENT_CERT --spi-x509cert-lookup--<provider>--ssl-cert-chain-prefix=CERT_CHAIN --spi-x509cert-lookup--<provider>-certificate-chain-length=10When configuring the HTTP headers, you need to make sure the values you are using correspond to the names of the headers forwarded by the proxy with the client certificate information.
Common options for configuring providers are:
| Option | Description | Supporting Providers |
|---|---|---|
ssl-client-cert |
The name of the header holding the client certificate |
all but |
ssl-cert-chain-prefix |
The prefix of the headers holding additional certificates in the chain and used to retrieve individual
certificates according to the length of the chain. For instance, a value |
|
ssl-cert-chain |
The name of the header holding the full certificate chain as a single value. All chain certificates are contained in one header rather than split across indexed headers. |
|
certificate-chain-length |
The maximum length of the certificate chain beyond the client certificate |
all but |
HAProxy can forward client certificates as base64-encoded DER using its ssl_c_der,base64 and ssl_c_chain_der,base64 sample fetches.
The haproxy provider reads the client certificate from the ssl-client-cert header and the certificate chain from the ssl-cert-chain header.
The options and defaults specific to haproxy are as follows:
| Option | Description | Default |
|---|---|---|
ssl-client-cert |
The name of the header holding the client certificate. |
(none) |
ssl-cert-chain |
The name of the header holding the full certificate chain as a single base64-encoded DER value. HAProxy’s |
(none) |
certificate-chain-length |
The maximum number of certificates to load from the chain header. |
1 |
Example HAProxy configuration:
http-request del-header Client-Cert
http-request del-header Client-Cert-Chain
http-request set-header Client-Cert %[ssl_c_der,base64] if { ssl_c_used } { ssl_c_verify 0 }
http-request set-header Client-Cert-Chain %[ssl_c_chain_der,base64] if { ssl_c_used } { ssl_c_verify 0 }Corresponding Keycloak configuration:
bin/kc.[sh|bat] start --spi-x509cert-lookup--provider=haproxy --spi-x509cert-lookup--haproxy--ssl-client-cert=Client-Cert --spi-x509cert-lookup--haproxy--ssl-cert-chain=Client-Cert-Chain --spi-x509cert-lookup--haproxy--certificate-chain-length=2If the number of intermediate certificates in your certificate chain is longer than the default, you must set the
certificate-chain-length option to an appropriate value. Otherwise, the provider will discard the request.
The NGINX SSL/TLS module does not expose the client certificate chain. Keycloak’s NGINX certificate lookup provider rebuilds it by using the Keycloak truststore.
If you are using this provider, see Configuring trusted certificates for how
to configure a Keycloak Truststore. The options and defaults specific to nginx are as follows:
| Option | Description | Default |
|---|---|---|
trust-proxy-verification |
Enable trusting NGINX proxy certificate verification, instead of forwarding the certificate to Keycloak and verifying it in Keycloak. |
false |
cert-is-url-encoded |
Whether the forwarded certificate is URL-encoded or not. In NGINX, this corresponds to the |
true |
If you stick to the header names mentioned in RFC 9440, you do not need to configure any additional options after selecting the rfc9440 provider.
The options and defaults specific to rfc9440 are as follows:
| Option | Description | Default |
|---|---|---|
ssl-client-cert |
The name of the header holding the client certificate |
Client-Cert |
ssl-cert-chain |
The name of the header holding additional certificates in the chain. This is not a prefix but the full name of the header because RFC 9440 mandates that the chain certificates are contained in one header. |
Client-Cert-Chain |
If the number of intermediate certificates in your certificate chain is longer than the default, you must set the
certificate-chain-length option to an appropriate value. Otherwise, the provider will discard the request.
The Traefik provider handles certificates forwarded by Traefik’s PassTLSClientCert middleware with pem: true.
Traefik sends the client certificate and any intermediate CA certificates as PEM blocks in a single X-Forwarded-Tls-Client-Cert header, separated by commas.
The traefik provider parses all certificates from this header.
Other than possibly changing the certificate-chain-length, you do not need to configure additional options for the traefik provider.
When running Keycloak behind a reverse proxy or load balancer, graceful shutdown ensures that in-flight requests complete successfully during server termination, preventing connection errors for clients.
Keycloak enables graceful HTTP shutdown by default with configurable timeouts.
The shutdown process consists of two phases:
During this phase, Keycloak signals to load balancers and proxies that it is preparing to shut down. The server’s readiness endpoint returns a "not ready" status, allowing the load balancer to stop routing new requests to this instance. Existing TLS and HTTP keepalive connections are allowed to drain naturally. The server continues to process existing requests.
After the pre-shutdown delay, Keycloak waits for in-flight HTTP requests to complete. Once the HTTP requests are complete, it uses the remaining time of the shutdown timeout to wait for caches to rebalance to avoid possible data loss. Once the timeout expires, the server shuts down regardless.
By default, Keycloak is configured with a 1-second pre-shutdown delay and a 10-second shutdown timeout. These defaults work well for most standard deployments where:
The load balancer reconfigures quickly (within 1 second)
Most requests complete within 1 second
The reverse proxy uses edge termination or re-encryption (not TLS passthrough)
Advanced users can adjust the shutdown timeouts using CLI options based on their deployment characteristics.
bin/kc.sh start --shutdown-delay=<duration> --shutdown-timeout=<duration>Available options:
--shutdown-delayLength of the pre-shutdown phase during which the server prepares for shutdown.
This period allows for load balancer reconfiguration and draining of TLS/HTTP keepalive connections.
Default: 1s
--shutdown-timeoutThe shutdown period waiting for currently running HTTP requests to finish.
Default: 10s
Both values accept duration formats: 1s (seconds), 500ms (milliseconds), 2m (minutes), etc.
Consider adjusting these values based on your deployment configuration. The following table shows example scenarios:
| Scenario | Delay | Timeout | Reason |
|---|---|---|---|
Load balancer polls readiness probe |
16s |
Assumptions:
Calculation:
|
|
TLS passthrough configuration |
10‑30s |
Longer delay allows keepalive connections to drain naturally and receive connection close signals. |
|
Long-running admin API requests |
10‑30s |
Admin operations may take longer than typical user requests. |
|
Test environments / quick restarts |
0s |
500ms |
Minimize shutdown time when graceful draining is not needed. |
Deployment orchestration reconfigures the proxy and drains connections before Pod termination |
0s |
No pre-shutdown delay needed if proxy is already reconfigured |
|
Combined: TLS passthrough plus polled readiness |
26‑56s |
Delays add up: time for load balancer detection + connection draining |
For production with TLS passthrough:
bin/kc.[sh|bat] start --shutdown-delay=30sFor load balancers that poll readiness:
bin/kc.[sh|bat] start --shutdown-delay=16sFor test environments:
bin/kc.[sh|bat] start --shutdown-delay=0s --shutdown-timeout=500ms|
The shutdown delay affects the minimum time required for a complete server restart.
In Kubernetes environments, ensure your |