Konfiguration af Keycloak v26 med Nginx Reverse Proxy i Docker: Løsning af konsolproblemer i forskellige riger

Overvinde Keycloak-konsolfejl med Nginx og Docker

Opsætning af Keycloak i en Docker-beholder med en Nginx omvendt proxy kan være en kraftfuld konfiguration til at administrere sikker adgang, men det kommer ikke uden udfordringer. 🐳 Når du migrerer Keycloak-databaser eller håndterer flere riger, kan uventede fejl ofte dukke op, hvilket skaber forvirring for administratorer.

Dette scenarie beskriver migreringen fra Keycloak v19.0.2 til Keycloak v26, hvor en "Kan ikke bestemme fejlmeddelelse" dukkede op på tværs af alle områder efter login. Sporing af problemet gennem Nginx-logfiler og Keycloak-fejllogfiler viste en mislykket HTTP-anmodning.

I lignende opsætninger kan et forkert konfigureret proxy- eller netværkslag udløse "502 bad gateway"-fejl, normalt på grund af problemer med, hvordan Nginx eller Docker dirigerer anmodninger til Keycloak. Dette problem kan kræve justeringer i proxyindstillinger, miljøvariabler eller SSL-konfigurationer for at sikre, at Keycloak fungerer problemfrit.

I denne vejledning gennemgår vi potentielle løsninger til fejlfinding af dette problem i Keycloak. Vi gennemgår nøglekonfigurationer, analyserer fejllogfiler og udforsker specifikke indstillinger, der kan hjælpe med at stabilisere Keycloak i en Docker-Nginx-opsætning. Ved udgangen vil du have indsigt i at løse sådanne problemer og sikre jævn, uafbrudt adgang til administrationskonsollen.

Detaljeret opdeling af Keycloak og Nginx-konfiguration

De scripts, vi udviklede til at konfigurere Keycloak bag en Nginx omvendt proxy, tjener en afgørende rolle i routing og styring af sikker adgang til Keycloak-administrationskonsollen. Nginx-konfigurationsfilen specificerer for eksempel en opstrøms blok, der definerer Keycloaks backend IP-adresse og port, hvilket gør det muligt for Nginx at dirigere anmodninger præcist. Dette er vigtigt for scenarier, hvor Keycloak-tjenesten opererer i et andet netværkssegment eller Docker-container. Ved at bruge fuldmagtsdirektiver som f.eks proxy_pass, gør vi det muligt for Nginx at fungere som mellemmand, håndtere eksterne anmodninger og videresende dem til Keycloaks interne serviceslutpunkt. Denne opsætning ses almindeligvis i produktionsmiljøer, hvor omvendte proxyer er nødvendige for belastningsbalancering og sikker adgang.

Inden for Nginx-konfigurationen er flere overskrifter sat med proxy_set_header kommandoer for at sikre, at Keycloak modtager alle klientoplysninger nøjagtigt. f.eks. X-Real-IP og X-Forwarded-Proto bruges til at videregive klientens IP og originale anmodningsprotokol. Disse oplysninger er vigtige, fordi Keycloak bruger dem til at generere nøjagtige omdirigerings-URL'er og administrere sikkerhedspolitikker. Et almindeligt problem i sådanne opsætninger er manglende overskrifter, hvilket kan føre til fejl, når Keycloak forsøger at autentificere brugere eller validere realms. Ved eksplicit at definere disse overskrifter sikrer administratorer, at Keycloak modtager den kontekst, som den skal bruge for at behandle anmodninger korrekt. Denne tilgang øger både sikkerhed og sammenhæng i, hvordan anmodninger administreres.

Docker Compose-filen, vi oprettede til Keycloak, forenkler implementeringen ved at bruge en env_fil for alle miljøvariabler. Dette gør det muligt for Docker-containeren at indlæse konfigurationer såsom databaselegitimationsoplysninger, Keycloak-værtsnavn og relative stier, hvilket gør den mere sikker og tilpasningsdygtig. Det er også praktisk at bruge en miljøfil, fordi den afkobler følsom information fra Docker Compose-filen og undgår hårdkodede værdier. Som et resultat bliver skift af databaser eller ændring af adgangsoplysninger problemfri, hvilket er særligt nyttigt i dynamiske miljøer, hvor tjenester ofte opdateres. I eksemplet sikrer miljøvariablen KC_PROXY_HEADERS sat til "xforwarded", at Keycloak forstår, at den er bag en proxy, og foretager justeringer i URL-generering og sessionsstyring i overensstemmelse hermed.

Ud over konfiguration leverede vi en Bash script, der fungerer som et simpelt sundhedstjek for at verificere Keycloaks tilgængelighed. Scriptet bruger krølle at udføre en HTTP-anmodning til Keycloak-slutpunktet og kontrollere, om statuskoden er lig med 200, hvilket indikerer, at tjenesten er operationel. I tilfælde af fejl genstarter scriptet Nginx-beholderen, hvilket tilbyder en form for automatisk gendannelse. Denne opsætning er ideel til produktionsmiljøer, hvor oppetid er kritisk, da det gør det muligt for tjenesten at selvhelbredende, hvis der opstår forbindelsesproblemer. Test af scripts som dette, sammen med den Python-baserede enhedstest for endpoint-tilgængelighed, styrker systemets stabilitet, hvilket giver administratorer ro i sindet ved at vide, at opsætningen vil underrette eller rette problemer proaktivt. Denne proaktive tilgang til ledelse er afgørende for at minimere nedetid og sikre problemfri adgang til Keycloaks administrationskonsollen.

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

Optimering af Keycloak til sikre og sømløse reverse proxy-operationer

Når du konfigurerer Keycloak bag en omvendt proxy som Nginx, kan flere yderligere overvejelser hjælpe med at sikre, at opsætningen er sikker, effektiv og stabil. Et afgørende aspekt er SSL-terminering - håndtering af HTTPS på Nginx-laget. Da Keycloak typisk lytter på HTTP i Docker, kan Nginx fungere som SSL-slutpunktet, aflaste krypteringen og reducere ressourcebelastningen på Keycloak. Denne opsætning gør det muligt for Nginx at kommunikere med Keycloak over HTTP og samtidig opretholde sikker HTTPS-adgang for slutbrugere. Derudover gemmes SSL-certifikater kun på Nginx, hvilket forenkler certifikathåndtering. Automatiserede værktøjer som Let's Encrypt kan strømline fornyelse, især med scripts, der genindlæser Nginx som certifikatopdatering.

En anden vigtig faktor er belastningsbalancering og skalering. For eksempel ved hjælp af Dockers netværkskonfigurationer kan administratorer oprette en opstrøms serverpulje i Nginx, der inkluderer flere Keycloak-containere, hvilket forbedrer belastningsfordelingen og tilgængeligheden. De proxy_pass direktiv peger på denne pulje, hvilket gør det muligt for Nginx at dirigere anmodninger på tværs af flere Keycloak-instanser. Denne tilgang er fordelagtig i miljøer med høj trafik, da den forhindrer, at en enkelt forekomst bliver overvældet. Derudover sikrer sessionpersistens, også kaldet sticky sessions, at brugerne forbliver forbundet til den samme instans, hvilket undgår autentificeringsproblemer. Sundhedstjek kan automatiseres ved hjælp af Nginx- eller Docker-scripts, overvåge Keycloaks tilgængelighed og genstarte forekomster, hvis der opstår fejl. 🛠️

Endelig er det afgørende at udnytte Keycloaks indbyggede målinger og logfiler for at vedligeholde og fejlfinde systemet. Keycloak kan generere detaljerede logfiler for hver anmodning, som, når de er parret med Nginx's adgangslogfiler, skaber et komplet revisionsspor. Overvågningsværktøjer som Prometheus og Grafana kan visualisere Keycloaks præstationsmålinger og advare administratorer om uregelmæssigheder, før de påvirker brugerne. I Nginx, indstilling fejl_log til debug niveau under opsætning fanger detaljerede oplysninger til diagnosticering af konfigurations- eller netværksproblemer. Tilsammen sikrer disse strategier en mere modstandsdygtig og sikker Keycloak-udrulning, hvilket gør den til en ideel løsning til virksomhedsgodkendelse bag en omvendt proxy.