Correction des erreurs HTTPS et de proxy de Keycloak en mode production

Le déploiement de Keycloak en mode production déclenche souvent des erreurs déroutantes, comme des consoles d'administration vides ou des exigences strictes de HTTPS. Une analyse technique approfondie publiée le 5 novembre 2026 explique comment résoudre ces problèmes à l'aide de Docker Compose, Nginx et de variables d'environnement spécifiques. Le guide démontre que la transmission correcte des en-têtes et la configuration du nom d'hôte sont essentielles pour une gestion stable des identités.

Ce qui s'est passé

L'article détaille un environnement de laboratoire reproductible utilisant Keycloak version 26.8.1, Nginx 1.31.8 et Postgres 18.6. L'auteur a rencontré plusieurs modes de défaillance standards lors du passage des paramètres de développement à ceux de production. Ceux-ci incluaient l'erreur « HTTPS requis » sur les pages de connexion, des interfaces d'administration vides dues au blocage du contenu mixte, et des messages « Paramètre invalide : redirect_uri » lors des flux d'authentification. Chaque erreur a été tracée jusqu'à la manière dont Keycloak interprète sa propre adresse réseau et son contexte de sécurité.

La cause racine de ces échecs est souvent une divergence entre l'URL visible par le navigateur et celle que Keycloak croit servir. Lorsqu'un proxy inverse termine les connexions TLS, Keycloak peut toujours générer des liens HTTP s'il n'est pas explicitement informé du contraire. Cela conduit les navigateurs à bloquer les ressources non sécurisées ou à rejeter les jetons parce que la revendication d'émetteur ne correspond pas au domaine sécurisé attendu. Le guide fournit des étapes de configuration exactes pour aligner le proxy, le conteneur et la logique de l'application.

Détails clés

• L'erreur « HTTPS requis » se produit lorsque Keycloak détecte une requête provenant d'une adresse IP publique via HTTP simple, ce qui est bloqué par défaut dans les domaines de production.
• La définition de KC_PROXY_HEADERS=xforwarded permet à Keycloak de faire confiance aux en-têtes envoyés par le proxy inverse, tels que X-Forwarded-Proto et X-Forwarded-Host.
• La variable KC_HOSTNAME doit être définie sur l'URL publique complète, y compris le schéma https, pour garantir que les jetons portent la revendication d'émetteur correcte.
• L'utilisation de KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true permet aux services internes de communiquer avec Keycloak via HTTP tout en maintenant la validité des jetons publics pour HTTPS.
• Les URI de redirection dans les applications clientes doivent correspondre exactement aux URI valides configurés, y compris le schéma, l'hôte et le port, pour éviter les échecs d'authentification.
• Le mode production nécessite KC_HTTP_ENABLED=true lorsque le TLS est terminé en périphérie, permettant à Keycloak d'écouter sur le port 8080 au sein du réseau Docker privé.

Contexte

Keycloak est une solution open source de gestion des identités et des accès qui repose fortement sur une génération précise des URL pour les jetons de sécurité et les redirections. Dans une configuration auto-hébergée typique, un proxy inverse comme Nginx se trouve devant le conteneur Keycloak pour gérer le chiffrement SSL/TLS. Cette architecture signifie que Keycloak lui-même fonctionne souvent via HTTP non chiffré à l'intérieur du réseau de conteneurs, tandis que le monde extérieur ne voit que HTTPS. Sans configuration appropriée, Keycloak ne peut pas distinguer une requête directe non sécurisée d'une requête sécurisée transmise par un proxy de confiance.

Le protocole OpenID Connect utilisé par Keycloak inclut un champ « issuer » (émetteur) dans chaque jeton, indiquant aux applications l'origine du jeton. Si cette URL d'émetteur utilise HTTP au lieu de HTTPS, ou si elle pointe vers un nom d'hôte interne Docker plutôt que vers le domaine public, les applications clientes rejetteront le jeton comme étant invalide. Cette fonctionnalité de sécurité empêche le vol de jetons mais exige un alignement précis entre la configuration du proxy et les paramètres internes de Keycloak.

Pourquoi c'est important

Pour les équipes gérant leurs propres logiciels, les fournisseurs d'identité constituent une infrastructure critique. Une instance Keycloak mal configurée peut verrouiller les administrateurs et rompre les connexions utilisateurs sur toutes les applications connectées. L'erreur « HTTPS requis » est particulièrement trompeuse car elle fonctionne souvent localement sur un ordinateur portable mais échoue sur un serveur privé virtuel. Comprendre que Keycloak traite les adresses IP publiques différemment des adresses privées aide les ingénieurs à diagnostiquer pourquoi une configuration qui fonctionne en développement casse en production.

De plus, des risques de sécurité surgissent lorsque les administrateurs prennent des raccourcis, comme désactiver entièrement les exigences SSL. Bien que cela puisse permettre le chargement de la page de connexion, cela expose les mots de passe et les jetons à l'interception. Configurer correctement le proxy inverse pour transmettre les en-têtes garantit que Keycloak maintient un contexte sécurisé sans avoir besoin de gérer directement les certificats. Cette approche simplifie le réseau interne tout en maintenant une sécurité de bout en bout pour les utilisateurs.

Un autre impact pratique concerne la stabilité de la console d'administration. Les erreurs de contenu mixte, où une page sécurisée tente de charger des scripts non sécurisés, rendent l'interface inutilisable. En veillant à ce que Keycloak génère des URL HTTPS pour toutes les ressources, les équipes évitent ces blocages au niveau du navigateur. Cette cohérence simplifie également le débogage pour les développeurs intégrant leurs applications, car les URI de redirection et les émetteurs de jetons restent prévisibles et corrects.

Ce que vous pouvez faire

• Configurez votre proxy inverse pour envoyer les en-têtes X-Forwarded-Proto, X-Forwarded-Host et X-Forwarded-Port au conteneur Keycloak.
• Définissez la variable d'environnement KC_PROXY_HEADERS sur xforwarded dans votre fichier Docker Compose pour activer le traitement des en-têtes.
• Définissez KC_HOSTNAME avec votre URL HTTPS publique complète pour corriger les divergences d'émetteur de jetons et assurer une génération d'URL cohérente.
• Activez KC_HTTP_ENABLED pour permettre à Keycloak d'accepter le trafic HTTP provenant du proxy tout en gardant l'accès externe sécurisé via TLS.
• Vérifiez que les URI de redirection de votre application correspondent exactement aux motifs autorisés dans Keycloak, en vérifiant les écarts entre http et https.
• Utilisez KC_HOSTNAME_BACKCHANNEL_DYNAMIC si les services internes doivent atteindre Keycloak via HTTP tout en maintenant la validité des jetons publics pour HTTPS.