<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>
<#import "/templates/options.adoc" as opts>
<#import "/templates/links.adoc" as links>

<@tmpl.guide
title="Configuring a reverse proxy"
summary="Configure {project_name} with a reverse proxy, API gateway, or load balancer."

includedOptions="proxy-* hostname hostname-admin http-relative-path shutdown-delay shutdown-timeout">

Distributed environments frequently require the use of a reverse proxy. {project_name} offers several options to securely integrate with such environments.

== Port to be proxied

{project_name} 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 <@links.server id="hostname"/> {section}.

The port `9000` is used for management, which includes endpoints for health checks and metrics as described in the  <@links.server id="management-interface"/> {section}.

You only need to proxy port `8443` (or `8080`) even when you use different host names for frontend/backend and administration as described at <@links.server id="configuration-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.

== Configure the reverse proxy headers

{project_name} will parse the reverse proxy headers based on the `proxy-headers` option which accepts several values:

* By default if the option is not specified, no reverse proxy headers are parsed. This should be used when no proxy is in use or with https passthrough.
* `forwarded` enables parsing of the `Forwarded` header as per https://www.rfc-editor.org/rfc/rfc7239.html[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`.

NOTE: If you are using a reverse proxy for anything other than https 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:

<@kc.start parameters="--proxy-headers forwarded"/>

WARNING: 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 https passthrough. Misconfiguration will leave {project_name} 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 this header is incorrectly configured, rogue clients can set this header and trick {project_name} 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.

NOTE: When using the `xforwarded` setting, the `X-Forwarded-Port` takes precedence over any port included in the `X-Forwarded-Host`.

NOTE: If the TLS connection is terminated at the reverse proxy (edge termination), enabling HTTP through the `http-enabled` setting is required.

== Different context path on reverse proxy

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

For more details on exposing {project_name} on different hostname or context path incl. Administration REST API and Console, see <@links.server id="hostname"/>.

== Enable sticky sessions

Typical cluster deployment consists of the load balancer (reverse proxy) and 2 or more {project_name} 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 {project_name} backend node.

The reason is, that {project_name} 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 {project_name} nodes can be like this:

* User sends initial request to see the {project_name} login screen

* This request is served by the frontend load balancer, which forwards it to some random node (eg. node1). Strictly said, the node doesn't need to be random, but can be chosen according to some other criteria (client IP address etc). It all depends on the implementation and configuration of underlying load balancer (reverse proxy).

* {project_name} creates authentication session with random ID (eg. 123) and saves it to the Infinispan cache.

* Infinispan distributed cache assigns the primary owner of the session based on the hash of session ID. See Infinispan documentation for more details around this. Let's assume that Infinispan assigned node2 to be the owner of this session.

* {project_name} creates the cookie AUTH_SESSION_ID with the format like <session-id>.<owner-node-id> . In our example case, it will be 123.node2 .

* Response is returned to the user with the {project_name} login screen and the AUTH_SESSION_ID cookie in the browser

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.

<@kc.start parameters="--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.

== Exposed path recommendations

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

[%autowidth]
|===
|{project_name} Path|Reverse Proxy Path|Exposed|Reason

|/
|-
|No
|When exposing all paths, admin paths are exposed unnecessarily.

|/admin/
| -
|No
|Exposed admin paths lead to an unnecessary attack vector.

|/realms/
|/realms/
|Yes
|This path is needed to work correctly, for example, for OIDC endpoints.

|/resources/
|/resources/
|Yes
|This path is needed to serve assets correctly. It may be served from a CDN instead of the {project_name} 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.

|===

We assume you run {project_name} on the root path `/` on your reverse proxy/gateway's public API.
If not, prefix the path with your desired one.

NOTE: If you configured a `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.

== Trusted Proxies

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:

<@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. 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:

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

[WARNING]
====
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.*

* Double check your use case needs reencrypt or edge TLS termination which implies using a proxy header for client certificate lookup. TLS passthrough is recommended as a more secure option
  when X.509 authentication is desired as it does not require passing the certificate via a proxy header. Client certificate lookup from a proxy header is applicable only to reencrypt
  and edge TLS termination.
* If passthrough is not an option, implement the following security measures:
** Configure your network so that {project_name} is isolated and can accept connections only from the proxy.
** Make sure that the proxy overwrites the header that is configured in `spi-x509cert-lookup--<provider>--ssl-client-cert` option.
** Pay extra attention to the `spi-x509cert-lookup--<provider>--trust-proxy-verification` setting. Make sure you enable it only if you can trust your proxy to verify the client certificate.
   Setting `spi-x509cert-lookup--<provider>--trust-proxy-verification=true` without the proxy verifying the client certificate chain will expose {project_name} to security vulnerability
   when a forged client certificate can be used for authentication.
====

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

[%autowidth]
|===
|Provider|Proxies

|apache
|Apache HTTP Server

|haproxy
|HAProxy

|nginx
|NGINX

|traefik
|Traefik (PassTLSClientCert middleware with `pem: true`)

|rfc9440
|Proxies that are compliant to link:https://datatracker.ietf.org/doc/rfc9440/[RFC 9440]

|envoy
|Envoy
|===

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

.Enable the corresponding proxy provider
<@kc.build parameters="--spi-x509cert-lookup--provider=<provider>"/>

.Configure the HTTP headers
<@kc.start parameters="--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:

[%autowidth]
|===
|Option|Description|Supporting Providers

|ssl-client-cert
| The name of the header holding the client certificate
| all but `traefik` and `envoy`, optional for `rfc9440`

|ssl-cert-chain-prefix
| The prefix of the headers holding additional certificates in the chain and used to retrieve individual
certificates accordingly to the length of the chain. For instance, a value `CERT_CHAIN` will tell the server
to load additional certificates from headers `CERT_CHAIN_0` to `CERT_CHAIN_9` if `certificate-chain-length` is set to `10`.
| `apache`, `haproxy`, `nginx`

|certificate-chain-length
| The maximum length of the certificate chain beyond the client certificate
| all but `envoy` (defaults to 1)

|===

=== Configuring the NGINX provider

The NGINX SSL/TLS module does not expose the client certificate chain. {project_name}'s NGINX certificate lookup provider rebuilds it by using the {project_name} truststore.

If you are using this provider, see <@links.server id="keycloak-truststore"/> for how
to configure a {project_name} Truststore. The options and defaults specific to `nginx` are as follows:

[%autowidth]
|===
|Option|Description|Default

|trust-proxy-verification
| Enable trusting NGINX proxy certificate verification, instead of forwarding the certificate to {project_name} and verifying it in {project_name}.
| false

|cert-is-url-encoded
| Whether the forwarded certificate is url-encoded or not. In NGINX, this corresponds to the `$ssl_client_cert` and `$ssl_client_escaped_cert` variables.
| true

|===

=== Configuring the rfc9440 provider

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:

[%autowidth]
|===
|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 your certificate chain is longer than the given default, you must define the option with an appropriate number.
Otherwise, the provider will discard the request.

=== Configuring the Traefik provider

The Traefik provider handles certificates forwarded by Traefik's link:https://doc.traefik.io/traefik/middlewares/http/passtlsclientcert/[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.

=== Configuring the Envoy provider

The Envoy provider will automatically retrieve the client certificate and optional certificate chain from the `x-forwarded-client-cert` header.
You do not need to configure additional options for the `envoy` provider.

[[graceful-http-shutdown]]
== Graceful HTTP shutdown

When running {project_name} behind a reverse proxy or load balancer, graceful shutdown ensures that in-flight requests complete successfully during server termination, preventing connection errors for clients.

{project_name} enables graceful HTTP shutdown by default with configurable timeouts.

=== Understanding shutdown phases

The shutdown process consists of two phases:

*Pre-shutdown delay*:: During this phase, {project_name} 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.

*Shutdown timeout*:: After the pre-shutdown delay, {project_name} stops accepting new requests and waits for in-flight HTTP requests to complete.
If requests are still running after the timeout expires, the server shuts down regardless.

=== Default behavior

By default, {project_name} is configured with a 1-second pre-shutdown delay and a 1-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)

=== Configuring shutdown timeouts

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

[source,bash]
----
bin/kc.sh start --shutdown-delay=<duration> --shutdown-timeout=<duration>
----

Available options:

`--shutdown-delay`::
Length 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-timeout`::
The shutdown period waiting for currently running HTTP requests to finish.
Default: `1s`

Both values accept duration formats: `1s` (seconds), `500ms` (milliseconds), `2m` (minutes), etc.

=== When to adjust shutdown timeouts

Consider adjusting these values based on your deployment configuration with the following example Scenarios:

[%autowidth,cols="2,>1,>1,3a"]
|===
|Scenario |Delay |Timeout |Reason

|Load balancer polls readiness probe
|16s
|
|Assumptions:

* 5s poll interval and a load balancer reconfiguring after two successive failed probes.
* 1s for reconfiguring the proxy.
* Proxy using TLS re-encrypt or edge termination.

Calculation:

* Allow three poll cycles for the load balancer to detect shutdown and the extra time for the load balancer to perform the reconfiguration:
+
`shutdown delay = 3 * 5s + 1s`

|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

|===

==== Example configurations

For production with TLS passthrough:

<@kc.start parameters="--shutdown-delay=30s --shutdown-timeout=1s"/>

For load balancers that poll readiness:

<@kc.start parameters="--shutdown-delay=16s --shutdown-timeout=1s"/>

For test environments:

<@kc.start parameters="--shutdown-delay=0s --shutdown-timeout=500ms"/>

[NOTE]
====
The shutdown delay affects the minimum time required for a complete server restart.
In Kubernetes environments, ensure your `terminationGracePeriodSeconds` is longer than the sum of `shutdown-delay` and `shutdown-timeout` to prevent forced termination.
====

</@tmpl.guide>
