„Keycloak v26“ konfigūravimas naudojant „Nginx Reverse Proxy“ programoje „Docker“: konsolės problemų sprendimas įvairiose srityse

„Keycloak“ konsolės klaidų įveikimas naudojant „Nginx“ ir „Docker“.

Keycloak nustatymas Docker konteineryje su Nginx atvirkštiniu tarpiniu serveriu gali būti galinga konfigūracija, skirta saugiai prieigai valdyti, tačiau tai neapsieina be iššūkių. 🐳 Perkeliant Keycloak duomenų bazes arba tvarkant kelias sritis, dažnai gali atsirasti netikėtų klaidų, kurios sukelia painiavą administratoriams.

Šiame scenarijuje aprašomas perkėlimas iš Keycloak v19.0.2 į Keycloak v26, kurio metu prisijungus visose srityse pasirodė pranešimas „Neįmanoma nustatyti klaidos“. Stebint problemą naudojant Nginx žurnalus ir Keycloak klaidų žurnalus, nustatyta, kad HTTP užklausa nepavyko.

Esant panašioms sąrankoms, netinkamai sukonfigūruotas tarpinis serveris arba tinklo sluoksnis gali sukelti „502 blogo šliuzo“ klaidas, dažniausiai dėl problemų, susijusių su „Nginx“ arba „Docker“ užklausų nukreipimu į „Keycloak“. Dėl šios problemos gali reikėti pakoreguoti tarpinio serverio nustatymus, aplinkos kintamuosius arba SSL konfigūracijas, kad būtų užtikrintas sklandus Keycloak veikimas.

Šiame vadove apžvelgsime galimus šios problemos sprendimo būdus Keycloak. Peržiūrėsime pagrindines konfigūracijas, analizuosime klaidų žurnalus ir išnagrinėsime konkrečius nustatymus, kurie gali padėti stabilizuoti „Keycloak“ naudojant „Docker-Nginx“ sąranką. Pabaigoje turėsite įžvalgų, kaip išspręsti tokias problemas ir užtikrinti sklandžią, nepertraukiamą prieigą prie administratoriaus pulto.

Išsamus „Keycloak“ ir „Nginx“ konfigūracijos suskirstymas

Scenarijai, kuriuos sukūrėme „Keycloak“ konfigūruoti už „Nginx“ atvirkštinio tarpinio serverio, atlieka svarbų vaidmenį nukreipiant ir valdant saugią prieigą prie „Keycloak“ administratoriaus konsolės. Pavyzdžiui, Nginx konfigūracijos failas nurodo prieš srovę blokas, apibrėžiantis „Keycloak“ IP adresą ir prievadą, leidžiantį „Nginx“ tiksliai nukreipti užklausas. Tai būtina scenarijuose, kai „Keycloak“ paslauga veikia kitame tinklo segmente arba „Docker“ konteineryje. Naudodami tarpinio serverio direktyvas, tokias kaip proxy_pass, leidžiame „Nginx“ veikti kaip tarpininkui, tvarkant išorines užklausas ir persiunčiant jas į „Keycloak“ vidinį paslaugos galinį tašką. Ši sąranka dažniausiai matoma gamybinėse aplinkose, kur apkrovos balansavimui ir saugiai prieigai reikalingi atvirkštiniai tarpiniai serveriai.

„Nginx“ konfigūracijoje nustatomos kelios antraštės proxy_set_header komandas, kad „Keycloak“ gautų visą kliento informaciją tiksliai. Pavyzdžiui, X-Real-IP ir X-Forwarded-Proto yra naudojami perduoti kliento IP ir pradinio užklausos protokolą. Ši informacija yra labai svarbi, nes „Keycloak“ ją naudoja tiksliems peradresavimo URL adresams generuoti ir saugos politikai valdyti. Dažna tokių sąrankų problema – trūksta antraščių, dėl kurių gali atsirasti klaidų, kai „Keycloak“ bando autentifikuoti vartotojus arba patvirtinti sritis. Aiškiai apibrėždami šias antraštes, administratoriai užtikrina, kad „Keycloak“ gautų kontekstą, kurio jai reikia tinkamai apdoroti užklausas. Šis metodas padidina užklausų valdymo saugumą ir nuoseklumą.

„Docker Compose“ failas, kurį sukūrėme „Keycloak“, supaprastina diegimą naudojant a env_file visiems aplinkos kintamiesiems. Tai leidžia „Docker“ konteineriui įkelti konfigūracijas, pvz., duomenų bazės kredencialus, „Keycloak“ pagrindinio kompiuterio pavadinimą ir santykinius kelius, todėl jis yra saugesnis ir pritaikomas. Aplinkos failo naudojimas taip pat yra praktiškas, nes jis atskiria jautrią informaciją nuo „Docker Compose“ failo, išvengiant sunkiai užkoduotų verčių. Dėl to duomenų bazių perjungimas arba prieigos kredencialų keitimas tampa sklandus, o tai ypač naudinga dinamiškoje aplinkoje, kur paslaugos dažnai atnaujinamos. Pavyzdyje aplinkos kintamasis KC_PROXY_HEADERS nustatytas į „xforwarded“ užtikrina, kad „Keycloak“ suprastų, kad yra už tarpinio serverio, ir atitinkamai koreguoja URL generavimą ir seansų valdymą.

Be konfigūracijos, mes pateikėme a Bash scenarijų, kuris naudojamas kaip paprastas sveikatos patikrinimas, norint patikrinti, ar „Keycloak“ yra. Scenarijus naudoja garbanoti atlikti HTTP užklausą į Keycloak galutinį tašką ir patikrinti, ar būsenos kodas yra lygus 200, nurodant, kad paslauga veikia. Gedimo atveju scenarijus iš naujo paleidžia „Nginx“ konteinerį ir siūlo automatinio atkūrimo formą. Ši sąranka idealiai tinka gamybinėms aplinkoms, kuriose veikimo laikas yra labai svarbus, nes tai leidžia paslaugai savaime išgydyti, jei kyla ryšio problemų. Tokių scenarijų testavimas kartu su Python pagrindu atliekamu galutinio taško pasiekiamumo vieneto testu sustiprina sistemos stabilumą, todėl administratoriai gali būti ramūs, žinant, kad sąranka praneš apie problemas arba jas ištaisys aktyviai. Šis iniciatyvus požiūris į valdymą yra labai svarbus siekiant sumažinti prastovos laiką ir užtikrinti sklandžią prieigą prie „Keycloak“ administratoriaus konsolė.

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“ optimizavimas saugioms ir sklandžioms atvirkštinio tarpinio serverio operacijoms

Konfigūruojant Keycloak už atvirkštinio tarpinio serverio, pvz Nginx, keletas papildomų aplinkybių gali padėti užtikrinti, kad sąranka būtų saugi, naši ir stabili. Vienas iš esminių aspektų yra SSL nutraukimas – HTTPS tvarkymas Nginx lygmenyje. Kadangi „Keycloak“ paprastai klausosi HTTP sistemoje „Docker“, „Nginx“ gali veikti kaip SSL galutinis taškas, perkeldamas šifravimą ir sumažindamas „Keycloak“ išteklių apkrovą. Ši sąranka leidžia „Nginx“ susisiekti su „Keycloak“ per HTTP, išlaikant saugią HTTPS prieigą galutiniams vartotojams. Be to, SSL sertifikatai saugomi tik „Nginx“, todėl sertifikatų valdymas supaprastinamas. Automatiniai įrankiai, tokie kaip „Let’s Encrypt“, gali supaprastinti atnaujinimą, ypač naudojant scenarijus, kurie iš naujo įkelia „Nginx“ atnaujinant sertifikatus.

Kitas svarbus veiksnys yra apkrovos balansavimas ir mastelio keitimas. Pavyzdžiui, naudodami „Docker“ tinklo konfigūracijas, administratoriai gali sukurti „Nginx“ serverio telkinį, kuriame yra keli „Keycloak“ konteineriai, pagerinantys apkrovos paskirstymą ir pasiekiamumą. The proxy_pass direktyva nurodo šį telkinį, leisdama Nginx nukreipti užklausas per kelis Keycloak egzempliorius. Šis metodas yra naudingas didelio srauto aplinkoje, nes jis apsaugo nuo pervargimo bet kokio atskiro egzemplioriaus. Be to, seanso išlikimas, dar vadinamas prilipusiais seansais, užtikrina, kad vartotojai liktų prisijungę prie to paties egzemplioriaus ir išvengtų autentifikavimo problemų. Sveikatos patikrinimai gali būti automatizuoti naudojant „Nginx“ arba „Docker“ scenarijus, stebint „Keycloak“ pasiekiamumą ir paleidžiant iš naujo, jei atsiranda gedimų. 🛠️

Galiausiai, norint prižiūrėti ir šalinti sistemą, labai svarbu naudoti „Keycloak“ integruotą metriką ir žurnalus. „Keycloak“ gali sugeneruoti išsamius kiekvienos užklausos žurnalus, kurie, suporuoti su „Nginx“ prieigos žurnalais, sukuria visą audito seką. Stebėjimo įrankiai, tokie kaip „Prometheus“ ir „Grafana“, gali vizualizuoti „Keycloak“ našumo metrikas, įspėdami administratorius apie anomalijas, kol jos nepaveiks naudotojų. Nginx, nustatymas error_log į debug lygis sąrankos metu fiksuoja išsamią informaciją, kad būtų galima diagnozuoti konfigūracijos ar tinklo problemas. Kartu šios strategijos užtikrina atsparesnį ir saugesnį „Keycloak“ diegimą, todėl tai yra idealus sprendimas įmonės lygio autentifikavimui naudojant atvirkštinį tarpinį serverį.