Corrección de errores de HTTPS y proxy en Keycloak en modo producción

Desplegar Keycloak en modo producción suele provocar errores confusos, como consolas de administración en blanco o requisitos estrictos de HTTPS. Un análisis técnico reciente publicado el 5 de noviembre de 2026 detalla cómo resolver estos problemas utilizando Docker Compose, Nginx y variables de entorno específicas. La guía demuestra que el reenvío adecuado de cabeceras y la configuración correcta del nombre de host son esenciales para una gestión estable de identidades.

Qué ocurrió

El artículo describe un entorno de laboratorio reproducible que utiliza Keycloak versión 26.8.1, Nginx 1.31.8 y Postgres 18.6. El autor se encontró con varios modos de fallo estándar al pasar de entornos de desarrollo a configuraciones de producción. Estos incluían el error "HTTPS required" en las páginas de inicio de sesión, interfaces de administración vacías debido al bloqueo de contenido mixto y mensajes de "Invalid parameter: redirect_uri" durante los flujos de autenticación. Cada error se rastreó hasta la forma en que Keycloak interpreta su propia dirección de red y contexto de seguridad.

La causa raíz de estos fallos suele ser una discrepancia entre la URL que ve el navegador y la URL que Keycloak cree estar sirviendo. Cuando un proxy inverso termina las conexiones TLS, Keycloak puede seguir generando enlaces HTTP si no se le indica explícitamente lo contrario. Esto lleva a los navegadores a bloquear recursos inseguros o a rechazar tokens porque la reclamación del emisor no coincide con el dominio seguro esperado. La guía proporciona pasos exactos de configuración para alinear el proxy, el contenedor y la lógica de la aplicación.

Detalles clave

• El error "HTTPS required" ocurre cuando Keycloak detecta una solicitud desde una dirección IP pública a través de HTTP simple, lo cual está bloqueado por defecto en los realms de producción.
• Establecer KC_PROXY_HEADERS=xforwarded permite a Keycloak confiar en las cabeceras enviadas por el proxy inverso, como X-Forwarded-Proto y X-Forwarded-Host.
• La variable KC_HOSTNAME debe establecerse con la URL pública completa, incluyendo el esquema https, para garantizar que los tokens lleven la reclamación de emisor correcta.
• El uso de KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true permite que los servicios internos se comuniquen con Keycloak mediante HTTP mientras mantienen válidos los tokens públicos para HTTPS.
• Las URI de redirección en las aplicaciones cliente deben coincidir exactamente con las URI válidas configuradas, incluyendo esquema, host y puerto, para evitar fallos de autenticación.
• El modo de producción requiere KC_HTTP_ENABLED=true cuando el TLS se termina en el borde, permitiendo que Keycloak escuche en el puerto 8080 dentro de la red privada de Docker.

Contexto

Keycloak es una solución de código abierto para la gestión de identidad y acceso que depende en gran medida de la generación precisa de URLs para tokens de seguridad y redirecciones. En una configuración típica autoalojada, un proxy inverso como Nginx se sitúa delante del contenedor de Keycloak para manejar el cifrado SSL/TLS. Esta arquitectura significa que Keycloak a menudo funciona sobre HTTP sin cifrar dentro de la red del contenedor, mientras que el mundo exterior solo ve HTTPS. Sin una configuración adecuada, Keycloak no puede distinguir entre una solicitud insegura directa y una solicitud segura reenviada por un proxy de confianza.

El protocolo OpenID Connect utilizado por Keycloak incluye un campo "issuer" (emisor) en cada token, que indica a las aplicaciones de dónde proviene el token. Si esta URL de emisor usa HTTP en lugar de HTTPS, o si apunta a un nombre de host interno de Docker en vez del dominio público, las aplicaciones cliente rechazarán el token como inválido. Esta característica de seguridad previene el robo de tokens pero requiere una alineación precisa entre la configuración del proxy y los ajustes internos de Keycloak.

Por qué importa

Para equipos que gestionan su propio software, los proveedores de identidad son infraestructura crítica. Una instancia mal configurada de Keycloak puede bloquear a los administradores y romper los inicios de sesión de usuario en todas las aplicaciones conectadas. El error "HTTPS required" es particularmente engañoso porque a menudo funciona localmente en un portátil pero falla en un servidor privado virtual. Comprender que Keycloak trata las direcciones IP públicas de manera diferente a las privadas ayuda a los ingenieros a diagnosticar por qué una configuración que funciona en desarrollo se rompe en producción.

Además, surgen riesgos de seguridad cuando los administradores toman atajos, como deshabilitar completamente los requisitos de SSL. Aunque esto podría hacer que la página de inicio de sesión cargue, expone contraseñas y tokens a la interceptación. Configurar adecuadamente el proxy inverso para reenviar cabeceras asegura que Keycloak mantenga un contexto seguro sin necesidad de manejar certificados directamente. Este enfoque mantiene la red interna simple mientras preserva la seguridad de extremo a extremo para los usuarios.

Otro impacto práctico es la estabilidad de la consola de administración. Los errores de contenido mixto, donde una página segura intenta cargar scripts inseguros, hacen que la interfaz sea inutilizable. Al asegurar que Keycloak genere URLs HTTPS para todos los recursos, los equipos evitan estos bloqueos a nivel de navegador. Esta consistencia también simplifica la depuración para desarrolladores que integran sus aplicaciones, ya que las URI de redirección y los emisores de tokens permanecen predecibles y correctos.

Qué puedes hacer

• Configura tu proxy inverso para enviar las cabeceras X-Forwarded-Proto, X-Forwarded-Host y X-Forwarded-Port al contenedor de Keycloak.
• Establece la variable de entorno KC_PROXY_HEADERS en xforwarded en tu archivo Docker Compose para habilitar el procesamiento de cabeceras.
• Define KC_HOSTNAME con tu URL pública HTTPS completa para corregir discrepancias en el emisor de tokens y asegurar una generación consistente de URLs.
• Habilita KC_HTTP_ENABLED para permitir que Keycloak acepte tráfico HTTP desde el proxy mientras mantiene el acceso externo seguro mediante TLS.
• Verifica que las URI de redirección de tu aplicación coincidan exactamente con los patrones permitidos en Keycloak, comprobando discrepancias entre http y https.
• Usa KC_HOSTNAME_BACKCHANNEL_DYNAMIC si los servicios internos necesitan alcanzar Keycloak vía HTTP mientras los tokens públicos siguen siendo válidos para HTTPS.