Configure Keycloak Behind a Reverse Proxy

In this article we will configure Keycloak behind a reverse proxy on Keycloak 26.7.3, using Nginx as the primary worked example and HAProxy as the equivalent.

A common Keycloak deployment places a reverse proxy or load balancer in front of Keycloak. Keycloak must trust forwarded headers so redirects, cookies, and the OIDC issuer stay on https:// with the public hostname. Certificate setup for Keycloak itself (re-encrypt or passthrough) lives in the HTTPS/TLS sibling listed under Related guides.

What this reverse-proxy lab teaches

At the end you will understand:

• Which termination pattern you are using: edge, re-encrypt, or passthrough
• Which Keycloak flags each pattern needs (KC_HTTP_ENABLED, KC_PROXY_HEADERS, KC_PROXY_TRUSTED_ADDRESSES, or KC_PROXY_PROTOCOL_ENABLED)
• How to overwrite X-Forwarded-* headers in Nginx and HAProxy so clients cannot inject false values
• Which application paths to expose publicly
• How to fix 403 Forbidden, http:// redirects, and wrong issuer URLs behind a proxy

Edge (proxy terminates TLS, plain HTTP to Keycloak)

  ┌────────┐  TLS   ┌───────┐  HTTP  ┌───────────────┐
  │ Client │ ─────► │ Proxy │ ─────► │ Keycloak :8080│
  └────────┘        └───────┘        └───────────────┘
                     overwrite         KC_HTTP_ENABLED
                     X-Forwarded-*     KC_PROXY_HEADERS
                                       KC_PROXY_TRUSTED_ADDRESSES

Choose a TLS termination pattern

Pick the pattern before you write proxy configs.

Keycloak 26.x no longer uses the legacy proxy=edge single flag from WildFly-era tutorials. Edge and re-encrypt layouts use proxy-headers (forwarded or xforwarded) plus http-enabled when the hop from proxy to Keycloak is plain HTTP.

Never trust client-supplied forwarding identity. The last trusted proxy should overwrite the Forwarded / X-Forwarded-* values Keycloak is configured to consume. Advanced header filtering lists live in the official reverse-proxy guide linked under References.

Which Keycloak paths should the proxy expose?

Do not reverse-proxy the management port 9000. For the application listener (8080 or 8443), expose only what clients need:

Exact path policies depend on your threat model. The table follows Keycloak's reverse-proxy path guidance: keep application-realm front doors reachable, and keep the master realm, Admin Console, and ops endpoints off the public hostname when you can.

Configure the Keycloak backend for edge TLS

The proxy decrypts HTTPS from clients and forwards plain HTTP to Keycloak on 8080. Keycloak must trust forwarded headers so redirects use https:// externally:

Your proxy must overwrite X-Forwarded-Proto, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Port, and related headers — not append or pass through client-supplied values.

Set KC_PROXY_TRUSTED_ADDRESSES to the source address Keycloak sees for your reverse proxy. Keycloak evaluates the connecting proxy IP, not the value inside X-Forwarded-For. On this lab host (Podman bridge/netavark with a published port), host Nginx appears inside the container as 10.88.0.1 (the podman0 gateway) — not 127.0.0.1, even though Nginx listens on loopback. Docker, Kubernetes, rootless pasta, or a proxy on another host will show a different peer address.

Start Keycloak for the edge lab. Publish HTTP on a loopback port that only the proxy will call:

podman run -d --name kc-proxy-backend --replace \
  -p 127.0.0.1:18080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  -e KC_HTTP_ENABLED=true \
  -e KC_HOSTNAME=https://auth.lab.local:18443 \
  -e KC_PROXY_HEADERS=xforwarded \
  -e KC_PROXY_TRUSTED_ADDRESSES=10.88.0.1 \
  quay.io/keycloak/keycloak:26.7.3 start

Confirm the flags before you wire the proxy:

podman run --rm \
  -e KC_HOSTNAME=https://auth.lab.local:18443 \
  -e KC_HTTP_ENABLED=true \
  -e KC_PROXY_HEADERS=xforwarded \
  -e KC_PROXY_TRUSTED_ADDRESSES=10.88.0.1 \
  quay.io/keycloak/keycloak:26.7.3 show-config

	kc.hostname =  https://auth.lab.local:18443 (ENV)
	kc.proxy-headers =  xforwarded (ENV)
	kc.proxy-trusted-addresses =  10.88.0.1 (ENV)
	kc.http-enabled =  true (ENV)

start disables HTTP by default, so edge mode must set KC_HTTP_ENABLED=true. See Keycloak start vs start-dev for why production mode expects this deliberate HTTP-or-HTTPS choice.

Nginx edge example

Create a lab certificate for the proxy front door (SAN must match the name clients use):

mkdir -p /tmp/kc-proxy-lab/certs /tmp/kc-proxy-lab/nginx
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /tmp/kc-proxy-lab/certs/proxy.key.pem \
  -out /tmp/kc-proxy-lab/certs/proxy.crt.pem \
  -days 365 \
  -subj '/CN=auth.lab.local' \
  -addext 'subjectAltName=DNS:auth.lab.local,DNS:localhost'
chmod 644 /tmp/kc-proxy-lab/certs/proxy.crt.pem /tmp/kc-proxy-lab/certs/proxy.key.pem

Run a standalone Nginx config that listens on 127.0.0.1:18443 and proxies to the Keycloak HTTP port. This avoids colliding with anything already bound on port 80. Use $remote_addr for X-Forwarded-For so Nginx replaces any client-supplied value instead of appending with $proxy_add_x_forwarded_for:

cat > /tmp/kc-proxy-lab/nginx/nginx-lab.conf <<'EOF'
worker_processes 1;
error_log /tmp/kc-proxy-lab/nginx/error.log;
pid /tmp/kc-proxy-lab/nginx/nginx.pid;
events { worker_connections 1024; }
http {
    access_log /tmp/kc-proxy-lab/nginx/access.log;
    map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
    }
    server {
        listen 127.0.0.1:18443 ssl;
        server_name auth.lab.local;

        ssl_certificate     /tmp/kc-proxy-lab/certs/proxy.crt.pem;
        ssl_certificate_key /tmp/kc-proxy-lab/certs/proxy.key.pem;

        location / {
            proxy_pass http://127.0.0.1:18080;
            proxy_http_version 1.1;
            proxy_set_header Host              $host;
            proxy_set_header X-Real-IP         $remote_addr;
            proxy_set_header X-Forwarded-For   $remote_addr;
            proxy_set_header X-Forwarded-Proto https;
            proxy_set_header X-Forwarded-Host  $host;
            proxy_set_header X-Forwarded-Port  18443;
            proxy_set_header Upgrade    $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_buffer_size 128k;
            proxy_buffers 4 256k;
            proxy_busy_buffers_size 256k;
        }
    }
}
EOF
nginx -c /tmp/kc-proxy-lab/nginx/nginx-lab.conf -t
nginx -c /tmp/kc-proxy-lab/nginx/nginx-lab.conf

On a production host you would usually drop a server { ... } block into /etc/nginx/conf.d/ and listen on 443, with the same overwrite headers and proxy_pass aimed at Keycloak.

After Keycloak logs show Listening on: http://0.0.0.0:8080, confirm basic connectivity through Nginx:

curl --noproxy '*' -sk -o /dev/null -w '%{http_code}\n' \
  --resolve auth.lab.local:18443:127.0.0.1 \
  https://auth.lab.local:18443/

302

Issuer and redirect checks are in Verify through the proxy below.

Verify through the proxy

Walk through these checks after the edge Nginx path works.

Redirect and scheme

Open the Admin Console URL users will bookmark. The location bar should stay on https:// after login redirects. If it drops to http://, KC_PROXY_HEADERS or the proxy’s X-Forwarded-Proto is wrong.

OIDC discovery issuer

curl --noproxy '*' -sk --resolve auth.lab.local:18443:127.0.0.1 \
  https://auth.lab.local:18443/realms/master/.well-known/openid-configuration \
  | grep -o '"issuer":"[^"]*"'

"issuer":"https://auth.lab.local:18443/realms/master"

The issuer must match the public URL — scheme, host, and port included.

HAProxy edge equivalent

HAProxy wants a combined certificate and key PEM. Build that file, then run an edge frontend on the same lab port. Explicitly replace forwarded headers instead of relying on option forwardfor alone:

cat /tmp/kc-proxy-lab/certs/proxy.crt.pem /tmp/kc-proxy-lab/certs/proxy.key.pem \
  > /tmp/kc-proxy-lab/certs/proxy.pem
chmod 644 /tmp/kc-proxy-lab/certs/proxy.pem

mkdir -p /tmp/kc-proxy-lab/haproxy
cat > /tmp/kc-proxy-lab/haproxy/haproxy.cfg <<'EOF'
global
    maxconn 256

defaults
    mode http
    timeout connect 5s
    timeout client  50s
    timeout server  50s

frontend fe_https
    bind 127.0.0.1:18443 ssl crt /tmp/kc-proxy-lab/certs/proxy.pem
    http-request set-header X-Forwarded-For %[src]
    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    http-request set-header X-Forwarded-Port 18443
    default_backend be_keycloak

backend be_keycloak
    server kc1 127.0.0.1:18080 check
EOF

Stop the lab Nginx process if it still holds 18443, then start HAProxy:

haproxy -c -f /tmp/kc-proxy-lab/haproxy/haproxy.cfg
haproxy -D -f /tmp/kc-proxy-lab/haproxy/haproxy.cfg \
  -p /tmp/kc-proxy-lab/haproxy/haproxy.pid

Re-run the discovery check from the verification section. The issuer should still be https://auth.lab.local:18443/realms/master.

Re-encrypt: HTTPS + proxy headers

Same header overwrite rules as edge, but the proxy opens a second TLS connection to Keycloak. Use separate host ports so the public frontend and Keycloak backend do not collide:

Generate Keycloak backend certificates (or reuse the PEM steps from the HTTPS/TLS guide), then start Keycloak with HTTPS and proxy headers:

# Backend certs for Keycloak (SAN auth.lab.local)
mkdir -p /tmp/kc-proxy-lab/kc-certs
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /tmp/kc-proxy-lab/kc-certs/server.key.pem \
  -out /tmp/kc-proxy-lab/kc-certs/server.crt.pem \
  -days 365 \
  -subj '/CN=auth.lab.local' \
  -addext 'subjectAltName=DNS:auth.lab.local,DNS:localhost'
chmod 644 /tmp/kc-proxy-lab/kc-certs/server.crt.pem \
  /tmp/kc-proxy-lab/kc-certs/server.key.pem

podman run -d --name kc-proxy-reencrypt --replace \
  -v /tmp/kc-proxy-lab/kc-certs:/opt/keycloak/conf:Z \
  -p 127.0.0.1:18444:8443 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  -e KC_HTTP_ENABLED=false \
  -e KC_HOSTNAME=https://auth.lab.local:18443 \
  -e KC_PROXY_HEADERS=xforwarded \
  -e KC_PROXY_TRUSTED_ADDRESSES=10.88.0.1 \
  -e KC_HTTPS_CERTIFICATE_FILE=/opt/keycloak/conf/server.crt.pem \
  -e KC_HTTPS_CERTIFICATE_KEY_FILE=/opt/keycloak/conf/server.key.pem \
  quay.io/keycloak/keycloak:26.7.3 start

Point Nginx at the backend HTTPS port. Enable SNI and trust the Keycloak certificate so verification works against auth.lab.local even though the upstream IP is 127.0.0.1:

cat > /tmp/kc-proxy-lab/nginx/nginx-reencrypt.conf <<'EOF'
worker_processes 1;
error_log /tmp/kc-proxy-lab/nginx/error-reencrypt.log;
pid /tmp/kc-proxy-lab/nginx/nginx-reencrypt.pid;
events { worker_connections 1024; }
http {
    access_log /tmp/kc-proxy-lab/nginx/access-reencrypt.log;
    map $http_upgrade $connection_upgrade {
        default upgrade;
        '' close;
    }
    server {
        listen 127.0.0.1:18443 ssl;
        server_name auth.lab.local;

        ssl_certificate     /tmp/kc-proxy-lab/certs/proxy.crt.pem;
        ssl_certificate_key /tmp/kc-proxy-lab/certs/proxy.key.pem;

        location / {
            proxy_pass https://127.0.0.1:18444;
            proxy_http_version 1.1;
            proxy_ssl_server_name on;
            proxy_ssl_name auth.lab.local;
            proxy_ssl_trusted_certificate /tmp/kc-proxy-lab/kc-certs/server.crt.pem;
            proxy_ssl_verify on;
            proxy_set_header Host              $host;
            proxy_set_header X-Real-IP         $remote_addr;
            proxy_set_header X-Forwarded-For   $remote_addr;
            proxy_set_header X-Forwarded-Proto https;
            proxy_set_header X-Forwarded-Host  $host;
            proxy_set_header X-Forwarded-Port  18443;
            proxy_set_header Upgrade    $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_buffer_size 128k;
            proxy_buffers 4 256k;
            proxy_busy_buffers_size 256k;
        }
    }
}
EOF

Stop any earlier lab Nginx or HAProxy that still holds 18443, then start the re-encrypt config:

nginx -c /tmp/kc-proxy-lab/nginx/nginx-reencrypt.conf -t
nginx -c /tmp/kc-proxy-lab/nginx/nginx-reencrypt.conf

After Keycloak logs show HTTPS listening on 8443, confirm discovery through the public proxy port:

curl --noproxy '*' -sk \
  --resolve auth.lab.local:18443:127.0.0.1 \
  https://auth.lab.local:18443/realms/master/.well-known/openid-configuration \
  | grep -o '"issuer":"[^"]*"'

"issuer":"https://auth.lab.local:18443/realms/master"

Restrict network access so only the proxy can reach Keycloak on 18444 — otherwise clients could connect directly and forge headers.

Passthrough: HTTPS + PROXY protocol

The proxy forwards the raw TLS stream. Keycloak terminates TLS and must hold a certificate valid for the public hostname. In passthrough mode, enable PROXY protocol on both the load balancer and Keycloak if Keycloak needs the original client IP:

• On Keycloak: KC_PROXY_PROTOCOL_ENABLED=true
• On the load balancer: enable send-proxy (HAProxy) or the equivalent PROXY protocol option
• Do not set KC_PROXY_HEADERS — Keycloak documents that proxy-protocol-enabled and proxy-headers cannot be used together, and the proxy cannot inject HTTP headers into encrypted traffic anyway

HAProxy TCP passthrough sketch:

frontend fe_tls
    mode tcp
    bind *:443
    default_backend be_keycloak_tls

backend be_keycloak_tls
    mode tcp
    server kc1 10.0.0.20:8443 send-proxy-v2

Use Keycloak HTTPS certificates from the HTTPS/TLS guide for the backend listener.

Run Keycloak under /auth behind a reverse proxy

A common public URL is https://example.com/auth instead of a dedicated hostname such as https://auth.example.com/. Keycloak supports that layout when the proxy and Keycloak agree on the context path. Three supported approaches:

1. Full hostname URL — set KC_HOSTNAME=https://example.com/auth so scheme, host, and path are fixed.
2. X-Forwarded-Prefix — with KC_PROXY_HEADERS=xforwarded, have the proxy set X-Forwarded-Prefix: /auth when the external path differs from what Keycloak serves.
3. KC_HTTP_RELATIVE_PATH=/auth — Keycloak itself serves under /auth, and the proxy forwards that path without rewriting it away.

Avoid arbitrary URL rewriting that strips or invents /auth without aligning one of those options. Mismatched path settings produce broken Admin Console assets, wrong redirect URIs, and discovery documents that clients cannot use.

Hostname v2 details for split admin URLs and strict mode are covered in the hostname sibling under Related guides.

Common problems

Summary

Keycloak behind a reverse proxy starts with choosing where TLS terminates. Edge mode terminates TLS at Nginx or HAProxy, enables HTTP on Keycloak, and relies on KC_PROXY_HEADERS plus KC_PROXY_TRUSTED_ADDRESSES so redirects and the OIDC issuer stay on the public https:// URL. Re-encrypt adds a second TLS hop to Keycloak on a separate backend port and still needs proxy headers. Passthrough keeps TLS on Keycloak and uses the PROXY protocol instead of header injection.

Overwrite forwarded headers at the proxy. Expose login and discovery paths carefully, and keep management port 9000 off the public proxy. After every change, confirm the Admin Console stays on https:// and that discovery returns the expected issuer.

References

• Configuring a reverse proxy — edge, re-encrypt, passthrough, proxy-headers, trusted addresses, exposed paths, PROXY protocol
• Configuring the hostname (v2) — full URL hostname with proxies and context paths
• Configuring TLS — Keycloak-side certificates for re-encrypt and passthrough
• NGINX Reverse Proxy — proxy_pass and upstream TLS options
• HAProxy Configuration Manual — header replacement, SSL bind, PROXY protocol