Configuring a reverse proxy

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.

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:

When using passthrough:

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:

The 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).

Keycloak parses the reverse proxy headers based on the proxy-headers option, which accepts several values:

For example:

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.

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:

When using a reverse proxy, Keycloak only requires certain paths to be exposed. The following table shows the recommended paths to expose.

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.

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:

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

A typical cluster deployment consists of a load balancer (reverse proxy) and two or more Keycloak servers on a private network. For performance purposes, it may be useful if the load balancer forwards all requests related to a particular browser session to the same Keycloak backend node.

The reason is that Keycloak uses an Infinispan distributed cache internally to store data related to the current authentication session and user session. The Infinispan distributed caches are configured with a limited number of owners. That means that session-related data is stored only on some cluster nodes, and the other nodes need to look up the data remotely if they want to access it.

For example, if an authentication session with ID 123 is saved in the Infinispan cache on node1, and then node2 needs to look up this session, it needs to send the request to node1 over the network to retrieve the session entity.

It is beneficial if a particular session entity is always available locally, which can be achieved with sticky sessions. The workflow in a cluster environment with a public frontend load balancer and two backend Keycloak nodes can be as follows:

From this point, it is beneficial if the load balancer forwards all subsequent requests to node2, as this is the node that owns the authentication session with ID 123 and hence Infinispan can look up this session locally. After authentication is finished, the authentication session is converted to a user session, which is also saved on node2 because it has the same ID 123.

Sticky sessions are not mandatory for a cluster setup; however, they improve performance for the reasons mentioned above. You need to configure your load balancer to use the AUTH_SESSION_ID cookie for session affinity. The appropriate procedure depends on your load balancer.

If your proxy supports session affinity without processing cookies from backend nodes, you should set the spi-sticky-session-encoder--infinispan--should-attach-route option to false in order to avoid attaching the node to cookies and just rely on the reverse proxy capabilities.

By default, the spi-sticky-session-encoder--infinispan--should-attach-route option value is true so that the node name is attached to cookies to indicate to the reverse proxy the node that subsequent requests should be sent to.

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 clients. You can configure how the server retrieves client certificate information depending on the proxy you are using.

The server supports some of the most common TLS termination proxies:

To configure how client certificates are retrieved from the requests, you need to:

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

The shutdown process consists of two phases:

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:

Advanced users can adjust the shutdown timeouts using CLI options based on their deployment characteristics.

Available options:

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: