Chapter 9. Configuring a reverse proxy

Red Hat build of Keycloak runs on the following ports by default:

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

The port 9000 is used for management, which includes endpoints for health checks and metrics as described in the Configuring the Management Interface chapter.

You only need to proxy port 8443 (or 8080) even when you use different host names for frontend/backend and administration as described at Configuring Red Hat build of Keycloak for production. You should not proxy port 9000 as health checks and metrics use those ports directly, and you do not want to expose this information to external callers.

Red Hat build of Keycloak will parse the reverse proxy headers based on the proxy-headers option which accepts several values:

For example:

bin/kc.[sh|bat] start --proxy-headers forwarded

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 this header is incorrectly configured, rogue clients can set this header and trick Red Hat build of Keycloak into thinking the client is connected from a different IP address than the actual address. This precaution can be more critical if you do any deny or allow listing of IP addresses.

By default Red Hat build of Keycloak is exposed through the root context path (/). If the proxy is using a different context path than Red Hat build of 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 Red Hat build of Keycloak is exposed through the reverse proxy on /auth. - Change the context path of Red Hat build of Keycloak itself to match the context path for the reverse proxy using the http-relative-path option.

For more details on exposing Red Hat build of Keycloak on different hostname or context path incl. Administration REST API and Console, see Configuring the hostname (v2).

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

The reason is, that Red Hat build of Keycloak is using Infinispan distributed cache under the covers for save data related to current authentication session and user session. The Infinispan distributed caches are configured with limited number of owners. That means that session related data are stored only in some cluster nodes and the other nodes need to lookup the data remotely if they want to access it.

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

It is beneficial if particular session entity is always available locally, which can be done with the help of sticky sessions. The workflow in the cluster environment with the public frontend load balancer and two backend Red Hat build of Keycloak nodes can be like this:

From this point, it is beneficial if load balancer forwards all the next requests to the node2 as this is the node, who is owner of the authentication session with ID 123 and hence Infinispan can lookup this session locally. After authentication is finished, the authentication session is converted to user session, which will be also saved on node2 because it has same ID 123 .

The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above. You need to configure your loadbalancer to stick over the AUTH_SESSION_ID cookie. The appropriate procedure to make this change depends on your loadbalancer.

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.

bin/kc.[sh|bat] start --spi-sticky-session-encoder--infinispan--should-attach-route=false

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 using a reverse proxy, Red Hat build of Keycloak only requires certain paths to be exposed. The following table shows the recommended paths to expose.

We assume you run Red Hat build of Keycloak on the root path / on your reverse proxy/gateway’s public API. If not, prefix the path with your desired one.

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/8

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. The value cannot be true when using the proxy-headers option.

This is useful when running behind a compatible https passthrough proxy because the request headers cannot be manipulated.

For example:

bin/kc.[sh|bat] start --proxy-protocol-enabled true

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 are able to configure how the server is going to retrieve client certificate information depending on the proxy you are using.

The server supports some of the most commons TLS termination proxies such as:

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=10

When configuring the HTTP headers, you need to make sure the values you are using correspond to the name of the headers forwarded by the proxy with the client certificate information.

Common options for configuring providers are:

When running Red Hat build of 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.

Red Hat build of Keycloak enables graceful HTTP shutdown by default with configurable timeouts.

bin/kc.sh start --shutdown-delay=<duration> --shutdown-timeout=<duration>

bin/kc.[sh|bat] start --shutdown-delay=30s --shutdown-timeout=1s

bin/kc.[sh|bat] start --shutdown-delay=16s --shutdown-timeout=1s

bin/kc.[sh|bat] start --shutdown-delay=0s --shutdown-timeout=500ms