Настройка Keycloak v26 с обратным прокси-сервером Nginx в Docker: решение проблем консоли в различных областях

Устранение ошибок консоли Keycloak с помощью Nginx и Docker

Настройка Keycloak в Docker-контейнере с обратным прокси-сервером Nginx может быть мощной конфигурацией для управления безопасным доступом, но она не обходится без проблем. 🐳 При миграции баз данных Keycloak или работе с несколькими областями часто могут возникать непредвиденные ошибки, что создает путаницу для администраторов.

В этом сценарии описан переход с Keycloak v19.0.2 на Keycloak v26, во время которого после входа в систему во всех областях появлялось сообщение «Невозможно определить сообщение об ошибке». Отслеживание проблемы с помощью журналов Nginx и журналов ошибок Keycloak показало неудавшийся HTTP-запрос.

В аналогичных конфигурациях неправильно настроенный прокси-сервер или сетевой уровень могут вызывать ошибки «502 плохой шлюз», обычно из-за проблем с тем, как Nginx или Docker направляет запросы в Keycloak. Эта проблема может потребовать корректировки настроек прокси-сервера, переменных среды или конфигураций SSL, чтобы обеспечить бесперебойную работу Keycloak.

В этом руководстве мы рассмотрим возможные решения этой проблемы в Keycloak. Мы рассмотрим ключевые конфигурации, проанализируем журналы ошибок и изучим конкретные настройки, которые могут помочь стабилизировать Keycloak в настройке Docker-Nginx. К концу вы получите представление о том, как решить такие проблемы и обеспечить беспрепятственный и бесперебойный доступ к консоли администратора.

Подробная разбивка конфигурации Keycloak и Nginx

Скрипты, которые мы разработали для настройки Keycloak за обратным прокси-сервером Nginx, играют важную роль в маршрутизации и управлении безопасным доступом к консоли администратора Keycloak. Например, в файле конфигурации Nginx указан вверх по течению блок, который определяет внутренний IP-адрес и порт Keycloak, позволяя Nginx точно направлять запросы. Это важно для сценариев, в которых служба Keycloak работает в другом сегменте сети или контейнере Docker. Используя прокси-директивы, такие как proxy_passмы позволяем Nginx выступать в качестве посредника, обрабатывая внешние запросы и перенаправляя их на конечную точку внутренней службы Keycloak. Эту настройку обычно можно увидеть в производственных средах, где обратные прокси-серверы необходимы для балансировки нагрузки и безопасного доступа.

В конфигурации Nginx несколько заголовков задаются с помощью proxy_set_header команды, чтобы гарантировать, что Keycloak точно получает всю информацию о клиенте. Например, X-Real-IP и X-Forwarded-Proto используются для передачи IP-адреса клиента и исходного протокола запроса. Эта информация важна, поскольку Keycloak использует ее для создания точных URL-адресов перенаправления и управления политиками безопасности. Распространенной проблемой в таких настройках является отсутствие заголовков, что может привести к ошибкам при попытке Keycloak аутентифицировать пользователей или проверить области. Явно определяя эти заголовки, администраторы гарантируют, что Keycloak получит контекст, необходимый для правильной обработки запросов. Такой подход повышает безопасность и согласованность управления запросами.

Файл Docker Compose, который мы создали для Keycloak, упрощает развертывание за счет использования env_file для всех переменных среды. Это позволяет контейнеру Docker загружать такие конфигурации, как учетные данные базы данных, имя хоста Keycloak и относительные пути, что делает его более безопасным и адаптируемым. Использование файла среды также практично, поскольку оно отделяет конфиденциальную информацию от файла Docker Compose, избегая жестко закодированных значений. В результате переключение баз данных или изменение учетных данных доступа становится беспрепятственным, что особенно полезно в динамических средах, где службы часто обновляются. В этом примере переменная среды KC_PROXY_HEADERS, для которой установлено значение «xforwarded», гарантирует, что Keycloak понимает, что находится за прокси-сервером, и соответствующим образом вносит коррективы в генерацию URL-адресов и управление сеансами.

Помимо настройки мы предоставили Баш скрипт, который служит простой проверкой работоспособности для проверки доступности Keycloak. В скрипте используется завиток для выполнения HTTP-запроса к конечной точке Keycloak и проверяет, равен ли код состояния 200, что указывает на то, что служба работает. В случае сбоя скрипт перезапускает контейнер Nginx, предлагая форму автоматического восстановления. Эта настройка идеально подходит для производственных сред, где время безотказной работы имеет решающее значение, поскольку позволяет службе самовосстанавливаться в случае возникновения проблем с подключением. Подобные сценарии тестирования, а также модульное тестирование доступности конечных точек на основе Python повышают стабильность системы, давая администраторам уверенность в том, что программа установки заранее уведомит или исправит проблемы. Такой проактивный подход к управлению жизненно важен для минимизации простоев и обеспечения беспрепятственного доступа к данным Keycloak. консоль администратора.

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

Оптимизация Keycloak для безопасных и бесперебойных операций обратного прокси

При настройке Keycloak за обратным прокси-сервером, например НгинксНесколько дополнительных соображений помогут обеспечить безопасность, производительность и стабильность установки. Одним из важнейших аспектов является завершение SSL — обработка HTTPS на уровне Nginx. Поскольку Keycloak обычно прослушивает HTTP внутри Docker, Nginx может выступать в качестве конечной точки SSL, разгружая шифрование и снижая нагрузку на ресурсы Keycloak. Эта настройка позволяет Nginx взаимодействовать с Keycloak через HTTP, сохраняя при этом безопасный доступ HTTPS для конечных пользователей. Кроме того, сертификаты SSL хранятся только в Nginx, что упрощает управление сертификатами. Автоматизированные инструменты, такие как Let’s Encrypt, могут упростить обновление, особенно с помощью сценариев, которые перезагружают Nginx при обновлении сертификатов.

Еще одним важным фактором является балансировка нагрузки и масштабирование. Например, используя сетевые конфигурации Docker, администраторы могут создать пул вышестоящих серверов в Nginx, который включает в себя несколько контейнеров Keycloak, улучшая распределение нагрузки и доступность. proxy_pass Директива указывает на этот пул, позволяя Nginx маршрутизировать запросы между несколькими экземплярами Keycloak. Этот подход полезен в средах с высоким трафиком, поскольку он предотвращает перегрузку любого отдельного экземпляра. Кроме того, сохранение сеанса, также называемое закрепленными сеансами, гарантирует, что пользователи остаются подключенными к одному и тому же экземпляру, избегая проблем с аутентификацией. Проверки работоспособности можно автоматизировать с помощью сценариев Nginx или Docker, отслеживая доступность Keycloak и перезапуская экземпляры в случае возникновения сбоев. 🛠️

Наконец, использование встроенных метрик и журналов Keycloak жизненно важно для обслуживания и устранения неполадок системы. Keycloak может генерировать подробные журналы для каждого запроса, которые в сочетании с журналами доступа Nginx создают полный контрольный журнал. Такие инструменты мониторинга, как Prometheus и Grafana, могут визуализировать показатели производительности Keycloak, предупреждая администраторов об аномалиях до того, как они повлияют на пользователей. В Nginx настройка error_log к debug Уровень во время установки собирает подробную информацию для диагностики проблем конфигурации или сети. Вместе эти стратегии обеспечивают более отказоустойчивое и безопасное развертывание Keycloak, что делает его идеальным решением для аутентификации корпоративного уровня за обратным прокси-сервером.