Behebung von Keycloak-HTTPS- und Proxy-Fehlern im Produktionsmodus

Die Bereitstellung von Keycloak im Produktionsmodus führt oft zu verwirrenden Fehlern, wie z. B. leeren Admin-Konsolen oder strengen HTTPS-Anforderungen. Ein kürzlich am 5. November 2026 veröffentlichter technischer Deep Dive zeigt auf, wie diese Probleme mit Docker Compose, Nginx und spezifischen Umgebungsvariablen gelöst werden können. Der Leitfaden demonstriert, dass eine korrekte Header-Weiterleitung und Hostname-Konfiguration für ein stabiles Identitätsmanagement unerlässlich sind.

Was passiert ist

Der Artikel beschreibt eine reproduzierbare Laborumgebung mit Keycloak Version 26.8.1, Nginx 1.31.8 und Postgres 18.6. Der Autor stieß beim Wechsel von der Entwicklungs- in die Produktionsumgebung auf mehrere Standardfehlermodi. Dazu gehörten der Fehler „HTTPS required“ auf Login-Seiten, leere Admin-Oberflächen aufgrund von Mixed-Content-Blockierung sowie die Meldung „Invalid parameter: redirect_uri“ während Authentifizierungsflüssen. Jeder dieser Fehler wurde auf die Art zurückgeführt, wie Keycloak seine eigene Netzwerkadresse und seinen Sicherheitskontext interpretiert.

Die Ursache dieser Fehler liegt oft in einer Diskrepanz zwischen der URL, die der Browser sieht, und der URL, von der Keycloak glaubt, sie bereitzustellen. Wenn ein Reverse-Proxy TLS-Verbindungen terminiert, generiert Keycloak möglicherweise weiterhin HTTP-Links, wenn es nicht explizit anders konfiguriert wird. Dies führt dazu, dass Browser unsichere Ressourcen blockieren oder Tokens ablehnen, weil die Issuer-Angabe (Aussteller) nicht zur erwarteten sicheren Domain passt. Der Leitfaden bietet exakte Konfigurationsschritte, um den Proxy, den Container und die Anwendungslogik in Einklang zu bringen.

Wichtige Details

• Der Fehler „HTTPS required“ tritt auf, wenn Keycloak eine Anfrage über reines HTTP an eine öffentliche IP-Adresse erkennt, was in Produktionsrealms standardmäßig blockiert wird.
• Die Einstellung KC_PROXY_HEADERS=xforwarded ermöglicht es Keycloak, den vom Reverse-Proxy gesendeten Headern wie X-Forwarded-Proto und X-Forwarded-Host zu vertrauen.
• Die Variable KC_HOSTNAME muss auf die vollständige öffentliche URL gesetzt werden, einschließlich des https-Schemas, um sicherzustellen, dass Tokens die korrekte Issuer-Angabe enthalten.
• Die Verwendung von KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true ermöglicht es internen Diensten, über HTTP mit Keycloak zu kommunizieren, während öffentliche Tokens für HTTPS gültig bleiben.
• Redirect-URIs in Client-Anwendungen müssen exakt mit den konfigurierten gültigen URIs übereinstimmen, einschließlich Schema, Host und Port, um Authentifizierungsfehler zu vermeiden.
• Im Produktionsmodus ist KC_HTTP_ENABLED=true erforderlich, wenn TLS am Rand (Edge) terminiert wird, damit Keycloak innerhalb des privaten Docker-Netzwerks auf Port 8080 lauschen kann.

Hintergrund

Keycloak ist eine Open-Source-Lösung für Identitäts- und Zugriffsmanagement, die stark auf präzise URL-Generierung für Sicherheitstokens und Weiterleitungen angewiesen ist. In einem typischen selbst gehosteten Setup sitzt ein Reverse-Proxy wie Nginx vor dem Keycloak-Container, um die SSL/TLS-Verschlüsselung zu übernehmen. Diese Architektur bedeutet, dass Keycloak selbst oft über unverschlüsseltes HTTP im Containernetzwerk läuft, während die Außenwelt nur HTTPS sieht. Ohne korrekte Konfiguration kann Keycloak nicht zwischen einer direkten unsicheren Anfrage und einer von einem vertrauenswürdigen Proxy weitergeleiteten sicheren Anfrage unterscheiden.

Das von Keycloak verwendete OpenID-Connect-Protokoll enthält in jedem Token ein „issuer“-Feld, das Anwendungen angibt, woher das Token stammt. Wenn diese Issuer-URL HTTP statt HTTPS verwendet oder auf einen internen Docker-Hostname statt auf die öffentliche Domain verweist, lehnen Client-Anwendungen das Token als ungültig ab. Dieses Sicherheitsmerkmal verhindert Token-Diebstahl, erfordert jedoch eine präzise Abstimmung zwischen der Proxy-Konfiguration und den internen Einstellungen von Keycloak.

Warum es wichtig ist

Für Teams, die ihre eigene Software betreiben, sind Identitätsanbieter kritische Infrastruktur. Eine falsch konfigurierte Keycloak-Instanz kann Administratoren aussperren und Benutzeranmeldungen über alle verbundenen Anwendungen hinweg unterbrechen. Der Fehler „HTTPS required“ ist besonders tückisch, da er lokal auf einem Laptop oft funktioniert, aber auf einem virtuellen privaten Server scheitert. Das Verständnis dafür, dass Keycloak öffentliche IP-Adressen anders behandelt als private Adressen, hilft Ingenieuren dabei, zu diagnostizieren, warum ein Setup, das in der Entwicklung funktioniert, in der Produktion versagt.

Darüber hinaus entstehen Sicherheitsrisiken, wenn Administratoren Abkürzungen nehmen, wie z. B. das vollständige Deaktivieren der SSL-Anforderungen. Zwar könnte dies dazu führen, dass die Login-Seite lädt, aber es setzt Passwörter und Tokens der Abfanggefahr aus. Eine korrekte Konfiguration des Reverse-Proxies zur Header-Weiterleitung stellt sicher, dass Keycloak einen sicheren Kontext beibehält, ohne Zertifikate direkt handhaben zu müssen. Dieser Ansatz hält das interne Netzwerk einfach und gewährleistet gleichzeitig Ende-zu-Ende-Sicherheit für Benutzer.

Ein weiterer praktischer Aspekt ist die Stabilität der Admin-Konsole. Mixed-Content-Fehler, bei denen eine sichere Seite versucht, unsichere Skripte zu laden, machen die Oberfläche unbrauchbar. Durch die Sicherstellung, dass Keycloak HTTPS-URLs für alle Ressourcen generiert, vermeiden Teams diese browserseitigen Blockierungen. Diese Konsistenz vereinfacht auch das Debugging für Entwickler, die ihre Apps integrieren, da die Redirect-URIs und Token-Issuer vorhersehbar und korrekt bleiben.

Was Sie tun können

• Konfigurieren Sie Ihren Reverse-Proxy so, dass er die Header X-Forwarded-Proto, X-Forwarded-Host und X-Forwarded-Port an den Keycloak-Container sendet.
• Setzen Sie die Umgebungsvariable KC_PROXY_HEADERS in Ihrer Docker-Compose-Datei auf xforwarded, um die Header-Verarbeitung zu aktivieren.
• Definieren Sie KC_HOSTNAME mit Ihrer vollständigen öffentlichen HTTPS-URL, um Mismatches beim Token-Issuer zu beheben und eine konsistente URL-Generierung sicherzustellen.
• Aktivieren Sie KC_HTTP_ENABLED, damit Keycloak HTTP-Traffic vom Proxy akzeptieren kann, während der externe Zugriff über TLS sicher bleibt.
• Überprüfen Sie, ob die Redirect-URIs Ihrer Anwendung exakt mit den in Keycloak erlaubten Mustern übereinstimmen, und achten Sie auf Unterschiede zwischen http und https.
• Verwenden Sie KC_HOSTNAME_BACKCHANNEL_DYNAMIC, wenn interne Dienste Keycloak über HTTP erreichen müssen, während öffentliche Tokens für HTTPS gültig bleiben sollen.