Fixing Keycloak HTTPS and proxy errors in production mode

Deploying Keycloak in production mode often triggers confusing errors such as blank admin consoles or strict HTTPS requirements. A recent technical deep dive published on November 5, 2026, outlines how to resolve these issues using Docker Compose, Nginx, and specific environment variables. The guide demonstrates that proper header forwarding and hostname configuration are essential for stable identity management.

What happened

The article details a reproducible lab environment using Keycloak version 26.8.1, Nginx 1.31.8, and Postgres 18.6. The author encountered several standard failure modes when moving from development to production settings. These included the "HTTPS required" error on login pages, blank admin interfaces due to mixed content blocking, and "Invalid parameter: redirect_uri" messages during authentication flows. Each error was traced back to how Keycloak interprets its own network address and security context.

The root cause of these failures is often a mismatch between the URL the browser sees and the URL Keycloak believes it is serving. When a reverse proxy terminates TLS connections, Keycloak may still generate HTTP links if not explicitly told otherwise. This leads to browsers blocking insecure resources or rejecting tokens because the issuer claim does not match the expected secure domain. The guide provides exact configuration steps to align the proxy, the container, and the application logic.

Key details

• The "HTTPS required" error occurs when Keycloak detects a request from a public IP address over plain HTTP, which is blocked by default in production realms.
• Setting KC_PROXY_HEADERS=xforwarded allows Keycloak to trust headers sent by the reverse proxy, such as X-Forwarded-Proto and X-Forwarded-Host.
• The KC_HOSTNAME variable must be set to the full public URL, including the https scheme, to ensure tokens carry the correct issuer claim.
• Using KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true enables internal services to communicate with Keycloak via HTTP while keeping public tokens valid for HTTPS.
• Redirect URIs in client applications must match the configured valid URIs exactly, including the scheme, host, and port, to avoid authentication failures.
• Production mode requires KC_HTTP_ENABLED=true when TLS is terminated at the edge, allowing Keycloak to listen on port 8080 within the private Docker network.

Background

Keycloak is an open-source identity and access management solution that relies heavily on accurate URL generation for security tokens and redirects. In a typical self-hosted setup, a reverse proxy like Nginx sits in front of the Keycloak container to handle SSL/TLS encryption. This architecture means Keycloak itself often runs over unencrypted HTTP inside the container network, while the outside world sees only HTTPS. Without proper configuration, Keycloak cannot distinguish between a direct insecure request and a secure request forwarded by a trusted proxy.

The OpenID Connect protocol used by Keycloak includes an "issuer" field in every token, which tells applications where the token came from. If this issuer URL uses HTTP instead of HTTPS, or if it points to an internal Docker hostname rather than the public domain, client applications will reject the token as invalid. This security feature prevents token theft but requires precise alignment between the proxy configuration and Keycloak's internal settings.

Why it matters

For teams running their own software, identity providers are critical infrastructure. A misconfigured Keycloak instance can lock out administrators and break user logins across all connected applications. The "HTTPS required" error is particularly deceptive because it often works locally on a laptop but fails on a virtual private server. Understanding that Keycloak treats public IP addresses differently than private ones helps engineers diagnose why a setup that works in development breaks in production.

Furthermore, security risks arise when administrators take shortcuts, such as disabling SSL requirements entirely. While this might make the login page load, it exposes passwords and tokens to interception. Properly configuring the reverse proxy to forward headers ensures that Keycloak maintains a secure context without needing to handle certificates directly. This approach keeps the internal network simple while maintaining end-to-end security for users.

Another practical impact is the stability of the admin console. Mixed content errors, where a secure page tries to load insecure scripts, render the interface unusable. By ensuring that Keycloak generates HTTPS URLs for all resources, teams avoid these browser-level blocks. This consistency also simplifies debugging for developers integrating their apps, as the redirect URIs and token issuers remain predictable and correct.

What you can do

• Configure your reverse proxy to send X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Port headers to the Keycloak container.
• Set the KC_PROXY_HEADERS environment variable to xforwarded in your Docker Compose file to enable header processing.
• Define KC_HOSTNAME with your full public HTTPS URL to fix token issuer mismatches and ensure consistent URL generation.
• Enable KC_HTTP_ENABLED to allow Keycloak to accept HTTP traffic from the proxy while keeping external access secure via TLS.
• Verify that your application's redirect URIs match the allowed patterns in Keycloak exactly, checking for http versus https discrepancies.
• Use KC_HOSTNAME_BACKCHANNEL_DYNAMIC if internal services need to reach Keycloak via HTTP while public tokens remain valid for HTTPS.