Configurando Keycloak v26 com proxy reverso Nginx no Docker: resolvendo problemas de console em vários domínios

Superando erros do console Keycloak com Nginx e Docker

Configurar o Keycloak em um contêiner Docker com um proxy reverso Nginx pode ser uma configuração poderosa para gerenciar o acesso seguro, mas não é isenta de desafios. 🐳 Ao migrar bancos de dados Keycloak ou lidar com vários domínios, muitas vezes podem surgir erros inesperados, criando confusão para os administradores.

Este cenário descreve a migração do Keycloak v19.0.2 para o Keycloak v26, durante a qual uma mensagem "Não foi possível determinar o erro" apareceu em todos os domínios após o login. Rastrear o problema por meio de logs do Nginx e logs de erros do Keycloak mostrou uma solicitação HTTP com falha.

Em configurações semelhantes, um proxy ou camada de rede mal configurado pode desencadear erros “502 gateway inválido”, geralmente devido a problemas em como o Nginx ou Docker roteia solicitações para o Keycloak. Este problema pode exigir ajustes nas configurações de proxy, variáveis ​​de ambiente ou configurações SSL para garantir que o Keycloak funcione perfeitamente.

Neste guia, examinaremos possíveis soluções para solucionar esse problema no Keycloak. Revisaremos as principais configurações, analisaremos logs de erros e exploraremos configurações específicas que podem ajudar a estabilizar o Keycloak em uma configuração Docker-Nginx. No final, você terá insights sobre como resolver esses problemas e garantir acesso tranquilo e ininterrupto ao admin console.

Análise detalhada da configuração do Keycloak e Nginx

Os scripts que desenvolvemos para configurar o Keycloak por trás de um proxy reverso Nginx desempenham um papel crítico no roteamento e no gerenciamento do acesso seguro ao console de administração do Keycloak. O arquivo de configuração Nginx, por exemplo, especifica um rio acima bloco que define o endereço IP e a porta de back-end do Keycloak, permitindo que o Nginx direcione as solicitações com precisão. Isso é essencial para cenários em que o serviço Keycloak opera em um segmento de rede ou contêiner Docker diferente. Usando diretivas de proxy como proxy_pass, permitimos que o Nginx atue como intermediário, lidando com solicitações externas e encaminhando-as para o endpoint de serviço interno do Keycloak. Essa configuração é comumente vista em ambientes de produção onde os proxies reversos são necessários para balanceamento de carga e acesso seguro.

Dentro da configuração do Nginx, vários cabeçalhos são definidos com proxy_set_header comandos para garantir que o Keycloak receba todas as informações do cliente com precisão. Por exemplo, X-Real-IP e X-Forwarded-Proto são usados ​​para passar o IP do cliente e o protocolo de solicitação original. Essas informações são essenciais porque o Keycloak as utiliza para gerar URLs de redirecionamento precisos e gerenciar políticas de segurança. Um problema comum nessas configurações é a falta de cabeçalhos, o que pode levar a erros quando o Keycloak tenta autenticar usuários ou validar domínios. Ao definir explicitamente esses cabeçalhos, os administradores garantem que o Keycloak receba o contexto necessário para processar as solicitações corretamente. Essa abordagem aumenta a segurança e a consistência na forma como as solicitações são gerenciadas.

O arquivo Docker Compose que criamos para Keycloak simplifica a implantação usando um arquivo_env para todas as variáveis ​​de ambiente. Isso permite que o contêiner Docker carregue configurações como credenciais de banco de dados, nome de host Keycloak e caminhos relativos, tornando-o mais seguro e adaptável. Usar um arquivo de ambiente também é prático porque separa informações confidenciais do arquivo Docker Compose, evitando valores codificados. Como resultado, a troca de bancos de dados ou a modificação de credenciais de acesso torna-se perfeita, o que é particularmente útil em ambientes dinâmicos onde os serviços são atualizados com frequência. No exemplo, a variável de ambiente KC_PROXY_HEADERS definida como “xforwarded” garante que o Keycloak entenda que está por trás de um proxy, fazendo ajustes na geração de URL e no gerenciamento de sessões de acordo.

Além da configuração, fornecemos um Bash script que serve como uma simples verificação de integridade para verificar a disponibilidade do Keycloak. O roteiro usa enrolar para realizar uma solicitação HTTP ao endpoint Keycloak e verifica se o código de status é igual a 200, indicando que o serviço está operacional. Em caso de falha, o script reinicia o container Nginx, oferecendo uma forma de recuperação automatizada. Essa configuração é ideal para ambientes de produção onde o tempo de atividade é crítico, pois permite que o serviço se auto-repare se ocorrerem problemas de conexão. Testar scripts como esse, junto com o teste de unidade baseado em Python para acessibilidade de endpoint, reforça a estabilidade do sistema, dando aos administradores tranquilidade sabendo que a configuração notificará ou corrigirá problemas de forma proativa. Esta abordagem proativa de gerenciamento é vital para minimizar o tempo de inatividade e garantir acesso contínuo aos recursos do Keycloak. console de administração.

upstream sso-mydomain-com {
    server 10.10.0.89:8080;
}
server {
    listen 443 ssl;
    server_name sso.mydomain.com;
    location / {
        proxy_pass http://sso-mydomain-com/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}
server {
    listen 8443 ssl;
    server_name sso.mydomain.com;
    error_log /usr/local/nginx/logs/sso_err.log debug;
    location / {
        proxy_pass http://sso-mydomain-com/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}

version: '3.9'
services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:26.0
    env_file:
      - .env
    ports:
      - "8080:8080"
    volumes:
      - /opt/keycloak/themes:/opt/keycloak/themes
      - /etc/localtime:/etc/localtime
    privileged: true
    command: start

import requests
def test_whoami_endpoint():
    url = "https://sso.mydomain.com:8443/auth/admin/master/console/whoami?currentRealm=master"
    headers = {"Content-Type": "application/json"}
    try:
        response = requests.get(url, headers=headers, verify=True)
        assert response.status_code == 200, "Expected 200 OK, got {}".format(response.status_code)
        print("Test passed: whoami endpoint accessible")
    except requests.ConnectionError:
        print("Connection error: Check Nginx reverse proxy and Keycloak availability")
    except AssertionError as e:
        print("Assertion error:", e)
# Run the test
test_whoami_endpoint()

#!/bin/bash
# Check if Keycloak is reachable via the /whoami endpoint
URL="http://10.10.0.89:8080/auth/admin/master/console/whoami"
STATUS_CODE=$(curl -s -o /dev/null -w "%{http_code}" $URL)
if [ "$STATUS_CODE" -ne 200 ]; then
    echo "Keycloak endpoint unavailable, restarting Nginx..."
    docker restart nginx
else
    echo "Keycloak endpoint is healthy."
fi

Otimizando Keycloak para operações de proxy reverso seguras e contínuas

Ao configurar o Keycloak atrás de um proxy reverso como Nginx, diversas considerações adicionais podem ajudar a garantir que a configuração seja segura, com bom desempenho e estável. Um aspecto crucial é a terminação SSL – tratamento de HTTPS na camada Nginx. Como o Keycloak normalmente escuta HTTP no Docker, o Nginx pode atuar como o endpoint SSL, descarregando a criptografia e reduzindo a carga de recursos no Keycloak. Esta configuração permite que o Nginx se comunique com o Keycloak por HTTP enquanto mantém o acesso HTTPS seguro para os usuários finais. Além disso, os certificados SSL são armazenados apenas no Nginx, simplificando o gerenciamento de certificados. Ferramentas automatizadas como Let’s Encrypt podem agilizar a renovação, especialmente com scripts que recarregam o Nginx conforme os certificados são atualizados.

Outro fator importante é o balanceamento e escalonamento de carga. Por exemplo, usando as configurações de rede do Docker, os administradores podem criar um pool de servidores upstream no Nginx que inclui vários contêineres Keycloak, melhorando a distribuição de carga e a disponibilidade. O proxy_pass A diretiva aponta para esse pool, permitindo que o Nginx roteie solicitações em várias instâncias do Keycloak. Essa abordagem é benéfica em ambientes de alto tráfego, pois evita que qualquer instância única fique sobrecarregada. Além disso, a persistência de sessão, também chamada de sessões fixas, garante que os usuários permaneçam conectados à mesma instância, evitando problemas de autenticação. As verificações de integridade podem ser automatizadas usando scripts Nginx ou Docker, monitorando a disponibilidade do Keycloak e reiniciando instâncias se ocorrerem falhas. 🛠️

Por fim, aproveitar as métricas e registros integrados do Keycloak é vital para manter e solucionar problemas do sistema. Keycloak pode gerar logs detalhados para cada solicitação, que, quando combinados com os logs de acesso do Nginx, criam uma trilha de auditoria completa. Ferramentas de monitoramento como Prometheus e Grafana podem visualizar as métricas de desempenho do Keycloak, alertando os administradores sobre anomalias antes que elas afetem os usuários. No Nginx, configuração log_erro para debug nível durante a configuração captura informações detalhadas para diagnosticar problemas de configuração ou rede. Juntas, essas estratégias garantem uma implantação do Keycloak mais resiliente e segura, tornando-o uma solução ideal para autenticação de nível empresarial por trás de um proxy reverso.