Налаштування Keycloak v26 із зворотним проксі Nginx у Docker: вирішення проблем консолі в різних сферах

Подолання помилок консолі Keycloak за допомогою Nginx і Docker

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

У цьому сценарії описано перехід із Keycloak v19.0.2 на Keycloak v26, під час якого після входу в усіх сферах з’явилося повідомлення «Неможливо визначити повідомлення про помилку». Відстеження проблеми за допомогою журналів Nginx і журналів помилок Keycloak показало помилку HTTP-запиту.

У подібних налаштуваннях неправильно налаштований проксі-сервер або мережевий рівень може викликати помилки «502 bad gateway», зазвичай через проблеми з тим, як 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-адреси та керування сеансами.

На додаток до конфігурації ми надали a Баш сценарій, який виконує функцію простої перевірки працездатності для перевірки доступності 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 за зворотним проксі-сервером, наприклад Nginx, кілька додаткових міркувань можуть допомогти переконатися, що налаштування безпечне, продуктивне та стабільне. Одним з ключових аспектів є термінація SSL — обробка HTTPS на рівні Nginx. Оскільки Keycloak зазвичай прослуховує HTTP в Docker, Nginx може діяти як кінцева точка SSL, розвантажуючи шифрування та зменшуючи навантаження ресурсів на Keycloak. Це налаштування дозволяє Nginx спілкуватися з Keycloak через HTTP, зберігаючи безпечний доступ HTTPS для кінцевих користувачів. Крім того, сертифікати SSL зберігаються лише в Nginx, що спрощує керування сертифікатами. Автоматизовані інструменти, такі як Let’s Encrypt, можуть спростити оновлення, особливо за допомогою сценаріїв, які перезавантажують Nginx під час оновлення сертифікатів.

Іншим важливим фактором є балансування навантаження та масштабування. Наприклад, використовуючи мережеві конфігурації Docker, адміністратори можуть створити пул вищестоящих серверів у Nginx, який включає кілька контейнерів Keycloak, покращуючи розподіл навантаження та доступність. The proxy_pass директива вказує на цей пул, дозволяючи Nginx маршрутизувати запити між кількома примірниками Keycloak. Цей підхід є корисним у середовищах із високим трафіком, оскільки він запобігає перевантаженню будь-якого окремого екземпляра. Крім того, постійність сеансу, яка також називається закріпленими сеансами, гарантує, що користувачі залишаються підключеними до того самого екземпляра, уникаючи проблем автентифікації. Перевірки працездатності можна автоматизувати за допомогою сценаріїв Nginx або Docker, моніторингу доступності Keycloak і перезапуску екземплярів у разі виникнення збоїв. 🛠️

Нарешті, використання вбудованих показників і журналів Keycloak є життєво важливим для обслуговування та усунення несправностей системи. Keycloak може генерувати докладні журнали для кожного запиту, які в поєднанні з журналами доступу Nginx створюють повний контрольний журнал. Інструменти моніторингу, такі як Prometheus і Grafana, можуть візуалізувати показники продуктивності Keycloak, сповіщаючи адміністраторів про аномалії, перш ніж вони вплинуть на користувачів. У Nginx налаштування error_log до debug рівень під час налаштування фіксує детальну інформацію для діагностики проблем конфігурації або мережі. Разом ці стратегії забезпечують більш стійке та безпечне розгортання Keycloak, що робить його ідеальним рішенням для автентифікації корпоративного рівня за зворотним проксі-сервером.