Konfigurere Keycloak v26 med Nginx Reverse Proxy i Docker: Løse konsollproblemer i forskjellige riker

Overvinne Keycloak Console-feil med Nginx og Docker

Å sette opp Keycloak i en Docker-beholder med en Nginx omvendt proxy kan være en kraftig konfigurasjon for å administrere sikker tilgang, men det kommer ikke uten utfordringer. 🐳 Når du migrerer Keycloak-databaser eller håndterer flere riker, kan det ofte dukke opp uventede feil, noe som skaper forvirring for administratorer.

Dette scenariet beskriver migreringen fra Keycloak v19.0.2 til Keycloak v26, hvor en "Kan ikke bestemme feilmelding" dukket opp på tvers av alle områder etter pålogging. Sporing av problemet gjennom Nginx-logger og Keycloak-feillogger viste en mislykket HTTP-forespørsel.

I lignende oppsett kan et feilkonfigurert proxy- eller nettverkslag utløse "502 bad gateway"-feil, vanligvis på grunn av problemer i hvordan Nginx eller Docker ruter forespørsler til Keycloak. Dette problemet kan kreve justeringer i proxy-innstillinger, miljøvariabler eller SSL-konfigurasjoner for å sikre at Keycloak fungerer sømløst.

I denne veiledningen vil vi gå gjennom potensielle løsninger for feilsøking av dette problemet i Keycloak. Vi vil gjennomgå nøkkelkonfigurasjoner, analysere feillogger og utforske spesifikke innstillinger som kan bidra til å stabilisere Keycloak i et Docker-Nginx-oppsett. Mot slutten vil du ha innsikt i å løse slike problemer og sikre jevn, uavbrutt tilgang til administrasjonskonsollen.

Detaljert oversikt over Keycloak og Nginx-konfigurasjon

Skriptene vi utviklet for å konfigurere Keycloak bak en Nginx omvendt proxy tjener en kritisk rolle i ruting og administrering av sikker tilgang til Keycloak-administrasjonskonsollen. Nginx-konfigurasjonsfilen spesifiserer for eksempel en oppstrøms blokk som definerer Keycloaks backend IP-adresse og port, slik at Nginx kan sende forespørsler nøyaktig. Dette er viktig for scenarier der Keycloak-tjenesten opererer i et annet nettverkssegment eller Docker-beholder. Ved å bruke proxy-direktiver som f.eks proxy_pass, gjør vi det mulig for Nginx å fungere som en mellommann, håndtere eksterne forespørsler og videresende dem til Keycloaks interne tjenesteendepunkt. Dette oppsettet er ofte sett i produksjonsmiljøer der omvendte proxyer er nødvendige for lastbalansering og sikker tilgang.

Innenfor Nginx-konfigurasjonen er flere overskrifter satt med proxy_set_header kommandoer for å sikre at Keycloak mottar all klientinformasjon nøyaktig. For eksempel X-Real-IP og X-Forwarded-Proto brukes til å sende klientens IP og originale forespørselsprotokoll. Denne informasjonen er viktig fordi Keycloak bruker den til å generere nøyaktige omdirigerings-URLer og administrere sikkerhetspolicyer. Et vanlig problem i slike oppsett er manglende overskrifter, noe som kan føre til feil når Keycloak prøver å autentisere brukere eller validere realms. Ved å eksplisitt definere disse overskriftene, sikrer administratorer at Keycloak mottar konteksten den trenger for å behandle forespørsler riktig. Denne tilnærmingen forbedrer både sikkerhet og konsistens i hvordan forespørsler administreres.

Docker Compose-filen vi opprettet for Keycloak forenkler distribusjonen ved å bruke en env_fil for alle miljøvariabler. Dette lar Docker-beholderen laste inn konfigurasjoner som databaselegitimasjon, Keycloak-vertsnavn og relative stier, noe som gjør den mer sikker og tilpasningsdyktig. Å bruke en miljøfil er også praktisk fordi den kobler sensitiv informasjon fra Docker Compose-filen, og unngår hardkodede verdier. Som et resultat blir det sømløst å bytte database eller endre tilgangslegitimasjon, noe som er spesielt nyttig i dynamiske miljøer der tjenester ofte oppdateres. I eksemplet sikrer miljøvariabelen KC_PROXY_HEADERS satt til "xforwarded" at Keycloak forstår at den ligger bak en proxy, og gjør justeringer i URL-generering og øktadministrasjon deretter.

I tillegg til konfigurasjon, ga vi en Bash skript som fungerer som en enkel helsesjekk for å bekrefte Keycloaks tilgjengelighet. Manuset bruker krølle å utføre en HTTP-forespørsel til Keycloak-endepunktet og sjekker om statuskoden er lik 200, noe som indikerer at tjenesten er operativ. I tilfelle feil starter skriptet Nginx-beholderen på nytt, og tilbyr en form for automatisert gjenoppretting. Dette oppsettet er ideelt for produksjonsmiljøer der oppetid er kritisk, siden det gjør at tjenesten kan reparere seg selv hvis det oppstår tilkoblingsproblemer. Testing av skript som dette, sammen med den Python-baserte enhetstesten for endepunkttilgjengelighet, forsterker systemets stabilitet, og gir administratorer trygghet i å vite at oppsettet vil varsle eller rette opp problemer proaktivt. Denne proaktive tilnærmingen til ledelse er avgjørende for å minimere nedetid og sikre sømløs tilgang til Keycloaks administrasjonskonsollen.

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

Optimalisering av Keycloak for sikre og sømløse omvendt proxy-operasjoner

Når du konfigurerer Keycloak bak en omvendt proxy som Nginx, kan flere andre hensyn bidra til å sikre at oppsettet er sikkert, effektivt og stabilt. Et avgjørende aspekt er SSL-terminering – håndtering av HTTPS på Nginx-laget. Siden Keycloak vanligvis lytter på HTTP i Docker, kan Nginx fungere som SSL-endepunktet, avlaste krypteringen og redusere ressursbelastningen på Keycloak. Dette oppsettet lar Nginx kommunisere med Keycloak over HTTP samtidig som den opprettholder sikker HTTPS-tilgang for sluttbrukere. I tillegg lagres SSL-sertifikater kun på Nginx, noe som forenkler sertifikatadministrasjonen. Automatiserte verktøy som Let's Encrypt kan strømlinjeforme fornyelsen, spesielt med skript som laster inn Nginx på nytt når sertifikater oppdateres.

En annen viktig faktor er lastbalansering og skalering. For eksempel, ved å bruke Dockers nettverkskonfigurasjoner, kan administratorer opprette en oppstrøms serverpool i Nginx som inkluderer flere Keycloak-beholdere, noe som forbedrer lastdistribusjon og tilgjengelighet. De proxy_pass direktivet peker på dette bassenget, og gjør det mulig for Nginx å rute forespørsler på tvers av flere Keycloak-forekomster. Denne tilnærmingen er gunstig i miljøer med mye trafikk, siden den forhindrer at en enkelt forekomst blir overveldet. I tillegg sørger øktpersistens, også kalt "sticky sessions", at brukerne forblir koblet til den samme forekomsten, og unngår autentiseringsproblemer. Helsesjekker kan automatiseres ved å bruke Nginx- eller Docker-skript, overvåke Keycloaks tilgjengelighet og starte forekomster på nytt hvis feil oppstår. 🛠️

Til slutt er det viktig å utnytte Keycloaks innebygde beregninger og logger for å vedlikeholde og feilsøke systemet. Keycloak kan generere detaljerte logger for hver forespørsel, som, når de er paret med Nginx sine tilgangslogger, skaper et komplett revisjonsspor. Overvåkingsverktøy som Prometheus og Grafana kan visualisere Keycloaks ytelsesmålinger, og varsle administratorer om uregelmessigheter før de påvirker brukerne. I Nginx, innstilling error_log til debug nivå under oppsett fanger opp detaljert informasjon for diagnostisering av konfigurasjons- eller nettverksproblemer. Sammen sikrer disse strategiene en mer spenstig og sikker Keycloak-distribusjon, noe som gjør den til en ideell løsning for autentisering i bedriftsgrad bak en omvendt proxy.