Konfigurace Keycloak v26 s Nginx Reverse Proxy v Dockeru: Řešení problémů s konzolou v různých sférách

Překonání chyb Keycloak Console pomocí Nginx a Docker

Nastavení Keycloak v Docker kontejneru s reverzním proxy serverem Nginx může být výkonnou konfigurací pro správu zabezpečeného přístupu, ale není to bez problémů. 🐳 Při migraci databází Keycloak nebo manipulaci s více sférami se často mohou objevit neočekávané chyby, které způsobují zmatek pro administrátory.

Tento scénář popisuje migraci z Keycloak v19.0.2 na Keycloak v26, během které se po přihlášení objevila ve všech sférách zpráva „Nelze určit chybovou zprávu“. Sledování problému prostřednictvím protokolů Nginx a protokolů chyb Keycloak ukázalo neúspěšný požadavek HTTP.

V podobných nastaveních může špatně nakonfigurovaný proxy nebo síťová vrstva vyvolat chyby „502 špatná brána“, obvykle kvůli problémům s tím, jak Nginx nebo Docker směrují požadavky na Keycloak. Tento problém může vyžadovat úpravy nastavení proxy, proměnných prostředí nebo konfigurací SSL, aby bylo zajištěno bezproblémové fungování Keycloak.

V této příručce si projdeme možná řešení pro řešení tohoto problému v Keycloak. Zkontrolujeme klíčové konfigurace, analyzujeme protokoly chyb a prozkoumáme konkrétní nastavení, která mohou pomoci stabilizovat Keycloak v rámci nastavení Docker-Nginx. Na konci budete mít přehled o řešení takových problémů a zajištění hladkého a nepřerušovaného přístupu do administrátorské konzole.

Podrobné rozdělení konfigurace Keycloak a Nginx

Skripty, které jsme vyvinuli pro konfiguraci Keycloak za reverzním proxy serverem Nginx, hrají klíčovou roli při směrování a správě zabezpečeného přístupu k administrátorské konzoli Keycloak. Konfigurační soubor Nginx například specifikuje proti proudu blok, který definuje backendovou IP adresu a port Keycloak, což umožňuje Nginxu přesně směrovat požadavky. To je nezbytné pro scénáře, kdy služba Keycloak funguje v jiném segmentu sítě nebo kontejneru Docker. Pomocí proxy direktiv, jako je např proxy_pass, umožňujeme Nginxu působit jako prostředník, vyřizovat externí požadavky a předávat je do interního koncového bodu služby Keycloak. Toto nastavení se běžně vyskytuje v produkčních prostředích, kde jsou pro vyrovnávání zátěže a bezpečný přístup nezbytné reverzní proxy.

V rámci konfigurace Nginx je nastaveno více hlaviček proxy_set_header příkazy, které zajistí, že Keycloak obdrží všechny klientské informace přesně. Například, X-Real-IP a X-Forwarded-Proto se používají k předání IP klienta a protokolu původního požadavku. Tyto informace jsou zásadní, protože je Keycloak používá ke generování přesných adres URL přesměrování a správě zásad zabezpečení. Běžným problémem v takových nastaveních jsou chybějící hlavičky, což může vést k chybám, když se Keycloak pokouší ověřit uživatele nebo ověřit sféry. Explicitním definováním těchto hlaviček správci zajistí, že Keycloak obdrží kontext, který potřebuje ke správnému zpracování požadavků. Tento přístup zvyšuje bezpečnost a konzistenci ve způsobu správy požadavků.

Soubor Docker Compose, který jsme vytvořili pro Keycloak, zjednodušuje nasazení pomocí env_file pro všechny proměnné prostředí. To umožňuje kontejneru Docker načíst konfigurace, jako jsou přihlašovací údaje k databázi, název hostitele Keycloak a relativní cesty, čímž je bezpečnější a přizpůsobivější. Použití souboru prostředí je také praktické, protože odděluje citlivé informace od souboru Docker Compose, čímž se vyhne pevně zakódovaným hodnotám. Výsledkem je bezproblémové přepínání databází nebo úprava přístupových údajů, což je užitečné zejména v dynamických prostředích, kde jsou služby často aktualizovány. V příkladu proměnná prostředí KC_PROXY_HEADERS nastavená na „xforwarded“ zajišťuje, že Keycloak chápe, že je za proxy serverem, a podle toho provede úpravy v generování URL a správě relace.

Kromě konfigurace jsme poskytli a Bash skript, který slouží jako jednoduchá kontrola stavu k ověření dostupnosti Keycloaku. Skript používá kučera k provedení požadavku HTTP na koncový bod Keycloak a zkontroluje, zda se stavový kód rovná 200, což znamená, že služba je funkční. V případě selhání skript restartuje kontejner Nginx a nabízí formu automatického obnovení. Toto nastavení je ideální pro produkční prostředí, kde je kritická doba provozuschopnosti, protože umožňuje, aby se služba sama uzdravila, pokud nastanou problémy s připojením. Testování skriptů, jako je tento, spolu s testem přístupnosti koncových bodů založeným na Pythonu posilují stabilitu systému a dávají administrátorům klid na duši, protože ví, že nastavení proaktivně upozorní nebo opraví problémy. Tento proaktivní přístup ke správě je zásadní pro minimalizaci prostojů a zajištění bezproblémového přístupu ke Keycloak's administrátorská konzole.

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

Optimalizace Keycloak pro bezpečné a bezproblémové reverzní operace proxy

Při konfiguraci Keycloak za reverzní proxy jako Nginx, několik dalších aspektů může pomoci zajistit, aby bylo nastavení bezpečné, výkonné a stabilní. Jedním z klíčových aspektů je ukončení SSL – zpracování HTTPS na vrstvě Nginx. Vzhledem k tomu, že Keycloak obvykle naslouchá na HTTP v rámci Dockeru, Nginx může fungovat jako koncový bod SSL, čímž snižuje zatížení šifrování a snižuje zatížení zdrojů na Keycloak. Toto nastavení umožňuje Nginx komunikovat s Keycloak přes HTTP při zachování zabezpečeného přístupu HTTPS pro koncové uživatele. SSL certifikáty jsou navíc uloženy pouze na Nginx, což zjednodušuje správu certifikátů. Automatizované nástroje, jako je Let’s Encrypt, mohou zefektivnit obnovu, zejména pomocí skriptů, které znovu načítají Nginx jako aktualizaci certifikátů.

Dalším důležitým faktorem je vyvažování zátěže a škálování. Například pomocí konfigurací sítě Docker mohou administrátoři vytvořit upstream serverový fond v Nginx, který obsahuje více kontejnerů Keycloak, čímž se zlepší rozložení zátěže a dostupnost. The proxy_pass Direktiva ukazuje na tento fond a umožňuje Nginx směrovat požadavky přes více instancí Keycloak. Tento přístup je výhodný v prostředích s vysokým provozem, protože zabraňuje zahlcení jakékoli jednotlivé instance. Perzistence relací, nazývaná také lepivé relace, navíc zajišťuje, že uživatelé zůstanou připojeni ke stejné instanci, čímž se zabrání problémům s autentizací. Kontroly stavu lze automatizovat pomocí skriptů Nginx nebo Docker, které monitorují dostupnost Keycloak a restartují instance, pokud dojde k selhání. 🛠️

A konečně, využití vestavěných metrik a protokolů Keycloak je zásadní pro údržbu a řešení problémů systému. Keycloak dokáže pro každý požadavek generovat podrobné protokoly, které po spárování s protokoly přístupu Nginx vytvoří kompletní auditní stopu. Monitorovací nástroje jako Prometheus a Grafana dokážou vizualizovat výkonnostní metriky Keycloak a upozornit administrátory na anomálie dříve, než ovlivní uživatele. V Nginx, nastavení error_log na debug úroveň během instalace zachycuje podrobné informace pro diagnostiku problémů s konfigurací nebo sítí. Tyto strategie společně zajišťují odolnější a bezpečnější nasazení Keycloak, což z něj činí ideální řešení pro ověřování podnikové úrovně za reverzní proxy.