Konfigurowanie Keycloak v26 z odwrotnym proxy Nginx w Dockerze: rozwiązywanie problemów z konsolą w różnych obszarach

Pokonywanie błędów konsoli Keycloak za pomocą Nginx i Dockera

Konfiguracja Keycloak w kontenerze Docker z odwrotnym proxy Nginx może być wydajną konfiguracją do zarządzania bezpiecznym dostępem, ale nie jest pozbawiona wyzwań. 🐳 Podczas migracji baz danych Keycloak lub obsługi wielu dziedzin często mogą pojawić się nieoczekiwane błędy, powodując zamieszanie dla administratorów.

Ten scenariusz opisuje migrację z Keycloak v19.0.2 do Keycloak v26, podczas której po zalogowaniu we wszystkich domenach pojawił się komunikat „Nie można określić komunikatu o błędzie”. Śledzenie problemu za pomocą dzienników Nginx i dzienników błędów Keycloak wykazało nieudane żądanie HTTP.

W podobnych konfiguracjach źle skonfigurowany serwer proxy lub warstwa sieciowa może powodować błędy „502 złej bramy”, zwykle z powodu problemów w sposobie, w jaki Nginx lub Docker kieruje żądania do Keycloak. Ten problem może wymagać dostosowania ustawień serwera proxy, zmiennych środowiskowych lub konfiguracji protokołu SSL, aby zapewnić bezproblemowe działanie Keycloak.

W tym przewodniku omówimy potencjalne rozwiązania tego problemu w Keycloak. Przeanalizujemy kluczowe konfiguracje, przeanalizujemy dzienniki błędów i zbadamy konkretne ustawienia, które mogą pomóc ustabilizować Keycloak w konfiguracji Docker-Nginx. Na koniec będziesz mieć wgląd w rozwiązanie takich problemów i zapewnienie płynnego, nieprzerwanego dostępu do konsoli administracyjnej.

Szczegółowy podział Keycloak i konfiguracji Nginx

Opracowane przez nas skrypty do konfigurowania Keycloak za odwrotnym proxy Nginx odgrywają kluczową rolę w routingu i zarządzaniu bezpiecznym dostępem do konsoli administracyjnej Keycloak. Na przykład plik konfiguracyjny Nginx określa plik pod prąd block definiujący adres IP i port zaplecza Keycloak, umożliwiając Nginx dokładne kierowanie żądań. Jest to istotne w scenariuszach, w których usługa Keycloak działa w innym segmencie sieci lub kontenerze Docker. Używając dyrektyw proxy, takich jak proxy_pass, umożliwiamy Nginx działanie w roli pośrednika, obsługę żądań zewnętrznych i przekazywanie ich do wewnętrznego punktu końcowego usługi Keycloak. Ta konfiguracja jest powszechnie spotykana w środowiskach produkcyjnych, gdzie odwrotne proxy są niezbędne do równoważenia obciążenia i bezpiecznego dostępu.

W konfiguracji Nginx ustawianych jest wiele nagłówków proxy_set_header polecenia, aby mieć pewność, że Keycloak otrzyma dokładne informacje o kliencie. Na przykład, X-Real-IP I X-Przesłane-Proto służą do przekazywania adresu IP klienta i protokołu oryginalnego żądania. Informacje te są niezbędne, ponieważ Keycloak wykorzystuje je do generowania dokładnych adresów URL przekierowań i zarządzania politykami bezpieczeństwa. Częstym problemem w takich konfiguracjach są brakujące nagłówki, co może prowadzić do błędów, gdy Keycloak próbuje uwierzytelnić użytkowników lub sprawdzić domeny. Jawnie definiując te nagłówki, administratorzy zapewniają, że Keycloak otrzyma kontekst niezbędny do prawidłowego przetwarzania żądań. Takie podejście zwiększa zarówno bezpieczeństwo, jak i spójność sposobu zarządzania żądaniami.

Plik Docker Compose, który utworzyliśmy dla Keycloak, upraszcza wdrażanie za pomocą pliku plik_środkowy dla wszystkich zmiennych środowiskowych. Dzięki temu kontener Docker może ładować konfiguracje, takie jak poświadczenia bazy danych, nazwa hosta Keycloak i ścieżki względne, dzięki czemu jest bezpieczniejszy i łatwiejszy do dostosowania. Korzystanie z pliku środowiska jest również praktyczne, ponieważ oddziela poufne informacje od pliku Docker Compose, unikając zakodowanych na stałe wartości. W rezultacie przełączanie baz danych lub modyfikowanie danych dostępu staje się płynne, co jest szczególnie przydatne w dynamicznych środowiskach, w których usługi są często aktualizowane. W tym przykładzie zmienna środowiskowa KC_PROXY_HEADERS ustawiona na „xforwarded” zapewnia, że ​​Keycloak rozumie, że znajduje się za serwerem proxy, odpowiednio dostosowując generowanie adresów URL i zarządzanie sesją.

Oprócz konfiguracji udostępniliśmy m.in Grzmotnąć skrypt służący jako prosta kontrola stanu w celu sprawdzenia dostępności Keycloak. Skrypt używa kędzior w celu wykonania żądania HTTP do punktu końcowego Keycloak i sprawdza, czy kod stanu jest równy 200, co oznacza, że ​​usługa działa. W przypadku awarii skrypt ponownie uruchamia kontener Nginx, oferując formę automatycznego odzyskiwania. Ta konfiguracja jest idealna dla środowisk produkcyjnych, w których czas sprawności ma kluczowe znaczenie, ponieważ umożliwia samonaprawę usługi w przypadku wystąpienia problemów z połączeniem. Testowanie takich skryptów wraz z testem jednostkowym opartym na Pythonie pod kątem dostępności punktów końcowych zwiększa stabilność systemu, dając administratorom spokój ducha, wiedząc, że konfiguracja będzie proaktywnie powiadamiać o problemach lub je naprawiać. To proaktywne podejście do zarządzania ma kluczowe znaczenie dla minimalizacji przestojów i zapewnienia bezproblemowego dostępu do Keycloak konsola administratora.

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

Optymalizacja Keycloak pod kątem bezpiecznych i bezproblemowych operacji zwrotnego proxy

Podczas konfigurowania Keycloak za odwrotnym proxy, np Nginx, kilka dodatkowych kwestii może pomóc zapewnić bezpieczeństwo, wydajność i stabilność konfiguracji. Jednym z kluczowych aspektów jest terminacja protokołu SSL — obsługa protokołu HTTPS w warstwie Nginx. Ponieważ Keycloak zazwyczaj nasłuchuje na HTTP w Dockerze, Nginx może działać jako punkt końcowy SSL, odciążając szyfrowanie i zmniejszając obciążenie zasobów Keycloak. Ta konfiguracja pozwala Nginx komunikować się z Keycloak przez HTTP, zachowując jednocześnie bezpieczny dostęp HTTPS dla użytkowników końcowych. Dodatkowo certyfikaty SSL są przechowywane tylko na Nginx, co upraszcza zarządzanie certyfikatami. Zautomatyzowane narzędzia, takie jak Let’s Encrypt, mogą usprawnić odnawianie, szczególnie w przypadku skryptów, które ponownie ładują Nginx w miarę aktualizacji certyfikatów.

Kolejnym ważnym czynnikiem jest równoważenie obciążenia i skalowanie. Na przykład, korzystając z konfiguracji sieci Dockera, administratorzy mogą utworzyć w Nginx pulę serwerów nadrzędnych, która zawiera wiele kontenerów Keycloak, poprawiając dystrybucję obciążenia i dostępność. The proxy_pass dyrektywa wskazuje na tę pulę, umożliwiając Nginx kierowanie żądań do wielu instancji Keycloak. Takie podejście jest korzystne w środowiskach o dużym natężeniu ruchu, ponieważ zapobiega przeciążeniu pojedynczej instancji. Dodatkowo trwałość sesji, zwana także sesjami trwałymi, zapewnia, że ​​użytkownicy pozostają połączeni z tą samą instancją, co pozwala uniknąć problemów z uwierzytelnianiem. Kontrole stanu można zautomatyzować za pomocą skryptów Nginx lub Docker, monitorując dostępność Keycloak i restartując instancje w przypadku wystąpienia awarii. 🛠️

Wreszcie, wykorzystanie wbudowanych wskaźników i dzienników Keycloak jest niezbędne do konserwacji systemu i rozwiązywania problemów. Keycloak może generować szczegółowe logi dla każdego żądania, które w połączeniu z dziennikami dostępu Nginx tworzą kompletną ścieżkę audytu. Narzędzia monitorujące, takie jak Prometheus i Grafana, mogą wizualizować wskaźniki wydajności Keycloak, ostrzegając administratorów o anomaliach, zanim wpłyną one na użytkowników. W Nginx ustawienie dziennik_błędów Do debug poziomie podczas instalacji przechwytuje szczegółowe informacje umożliwiające diagnozowanie problemów z konfiguracją lub siecią. Razem te strategie zapewniają bardziej odporne i bezpieczne wdrożenie Keycloak, co czyni go idealnym rozwiązaniem do uwierzytelniania klasy korporacyjnej za odwrotnym proxy.