PegaProx mit Keycloak über OIDC
Git-taugliche Einrichtungsanleitung, rekonstruiert aus „OIDC Endpunkte korrigieren“ vom 09.09.2026. Alle internen Adressen, Namen und IPs sind Beispielwerte aus der Unterhaltung und müssen für andere Umgebungen ersetzt werden. Keine Zugangsdaten enthalten.
Nachweis und Grenzen
Der Benutzer bestätigte abschließend, dass die Anmeldung und Rollenzuordnung funktionieren. Belegt sind erfolgreiche Discovery-Abfragen mit curl und Python, der Claim groups: ["pegaprox-admins"] und die abschließende Zuordnung in PegaProx. Nach dem Vorschlag eines PegaProx-Neustarts und alternativ eines kurzen Tests ohne TLS-Prüfung wurde Erfolg gemeldet; welche Maßnahme tatsächlich ausgeführt wurde, ist nicht eindeutig dokumentiert. Der finale Schalterstand von „Skip SSL verification“ ist nicht belegt. Diese Anleitung setzt ihn für den sicheren Zielzustand auf OFF und fordert einen erneuten Test.
Exakte PegaProx- und Keycloak-Versionen fehlen. UI-Bezeichnungen beziehen sich auf die Unterhaltung; ergänzende CA- und CLI-Schritte sind reproduzierbare Anleitungen, keine Behauptung über bereits ausgeführte Änderungen. Ein Quellcode-Patch ist nicht als ausgeführt belegt und wird nicht benötigt, wenn Discovery funktioniert.
Repo-Struktur
README.md
docs/troubleshooting.md
docs/verification.md
example-configs/keycloak-client.example.json
example-configs/pegaprox-groups-scope.example.json
example-configs/pegaprox-oidc.example.json
example-configs/discovery.example.json
example-configs/pegaprox-ca.conf.example
scripts/check-discovery.py
.gitignore
1. Voraussetzungen und Beispielumgebung
| Zweck | Beispielwert |
|---|---|
| Keycloak | https://9.99.30.11:8443 |
| Realm | service.heim.lan |
| Client ID (Großschreibung beachten) | PegaProx |
| PegaProx | https://9.99.30.13:5000 |
| Callback | https://9.99.30.13:5000/oidc/callback |
| Zertifikats-CN | keycloak.service.heim.lan |
| Aussteller des Serverzertifikats | HEIMLAN_SubCA |
| System-CA-Bundle | /etc/ssl/certs/ca-certificates.crt |
| PegaProx-Dienst / Benutzer | pegaprox |
| Python / Anwendung | /usr/bin/python3, /usr/lib/pegaprox/pegaprox_multi_cluster.py |
Keycloak und PegaProx sind bereits installiert. Benötigt werden Realm-Administrationsrechte, ein lokaler PegaProx-Administrator, Netzwerkzugriff vom Browser auf beide Dienste und vom PegaProx-Dienst auf Keycloak:8443 sowie korrekte Systemzeiten. Für Diagnosen: curl, Python 3 mit requests; optional die Keycloak Admin CLI.
Die Adressen 9.99.30.x wurden intern verwendet, gehören aber nicht zu den privaten RFC1918-Netzen. Nicht als frei verfügbare Lab-Adressen übernehmen. Der alternative Name auth.service.heim.lan war im Chat nur ein Vorschlag, kein nachgewiesener finaler Issuer. Ein Wechsel von IP auf DNS erfordert konsistente Issuer-, Zertifikats- und Client-Einstellungen.
2. Keycloak-Client anlegen
Im Realm service.heim.lan: Clients → Create client. Client type OpenID Connect, Client ID PegaProx.
| Einstellung | Wert |
|---|---|
| Client authentication | ON (vertraulicher Client) |
| Authorization | OFF |
| Standard flow | ON |
| Direct access grants | OFF |
| Implicit flow | OFF |
| Service accounts roles | OFF |
| Root URL / Home URL | https://9.99.30.13:5000 |
| Valid redirect URIs | https://9.99.30.13:5000/oidc/callback |
| Web origins | https://9.99.30.13:5000 |
Speichern. Unter Credentials das erzeugte Client Secret ausschließlich in PegaProx eintragen. Es wird weder in dieser Repo-Struktur noch in einem Export gespeichert. Die JSON-Datei ist eine Vorlage für einen neuen Client; bei vorhandenem Client die UI-Werte abgleichen, nicht blind erneut importieren.
Die beobachtete Anmeldung verwendet Authorization Code Flow mit PKCE S256 (response_type=code, code_challenge_method=S256). Eine zwingende PKCE-Clientrichtlinie war nicht nachgewiesen. Post-Logout-Redirects sind für diesen Login nicht nötig; nur bei tatsächlich eingerichtetem Logout mit dessen exaktem Rücksprungziel ergänzen. Das früher vorgeschlagene https://9.99.30.13:5000/* ist kein nachgewiesener finaler Logout-Wert.
3. TLS-Vertrauen herstellen und Discovery prüfen
Im tatsächlichen PegaProx-Host bzw. Container prüfen, nicht nur auf einem anderen Rechner:
curl --fail --show-error --silent \
'https://9.99.30.11:8443/realms/service.heim.lan/.well-known/openid-configuration'
python3 scripts/check-discovery.py
Erwartet: HTTP 200, JSON und exakt der konfigurierte Issuer. Die Endpunkte werden aus Discovery bezogen:
| Feld | Beispiel-URL |
|---|---|
| issuer | https://9.99.30.11:8443/realms/service.heim.lan |
| Discovery | https://9.99.30.11:8443/realms/service.heim.lan/.well-known/openid-configuration |
| authorization_endpoint | https://9.99.30.11:8443/realms/service.heim.lan/protocol/openid-connect/auth |
| token_endpoint | https://9.99.30.11:8443/realms/service.heim.lan/protocol/openid-connect/token |
| jwks_uri | https://9.99.30.11:8443/realms/service.heim.lan/protocol/openid-connect/certs |
| userinfo_endpoint | https://9.99.30.11:8443/realms/service.heim.lan/protocol/openid-connect/userinfo |
Der UserInfo-Pfad ist der Keycloak-Standard; sein vollständiger Wert war im ursprünglichen curl-Auszug abgeschnitten. Die anderen Endpunkte waren sichtbar. Keycloak dokumentiert Discovery und diese Endpunkte in der OIDC-Dokumentation.
Falls die interne CA noch fehlt, auf Debian/Ubuntu im PegaProx-System die vertrauenswürdig beschaffte öffentliche Root-CA installieren (Dateiname hier neu gewähltes Beispiel):
sudo install -m 0644 /pfad/zur/geprueften/heimlan-root-ca.crt \
/usr/local/share/ca-certificates/heimlan-root-ca.crt
sudo update-ca-certificates
sudo systemctl restart pegaprox
Die Datei muss ein PEM-Zertifikat enthalten; pro .crt eine CA. Die Serverkette sollte benötigte Intermediate-Zertifikate liefern. Fehlende Intermediate-Ketten am Keycloak-TLS-Endpunkt korrigieren. Keine privaten Schlüssel kopieren. Bei Containern die CA dauerhaft im Image oder vorgesehenen Truststore bereitstellen; Änderungen nur am Host reichen nicht.
Im Chat vertrauten curl und Python der CA bereits: curl meldete „SSL certificate verify ok“, IP-SAN passend zu 9.99.30.11, HTTP 200. requests und certifi verwendeten beide das System-Bundle. Ein grundsätzlich defektes Zertifikat oder ein abweichendes certifi-Bundle war damit für diese Shell nicht belegt.
Nach einer CA-/Dienständerung PegaProx neu starten und den integrierten OIDC-Test wiederholen. Bei weiterem Fehler siehe TLS-Diagnose. „Skip SSL verification“ bleibt im Zielzustand OFF; ein erfolgreicher Test nur mit abgeschalteter Prüfung ist kein abgeschlossener TLS-Fix.
4. PegaProx-OIDC-Einstellungen
OIDC / Entra ID öffnen und OIDC aktivieren, soweit separat vorhanden:
| Einstellung | Wert |
|---|---|
| Provider | Generic OIDC (generic) |
| Issuer / Authority | https://9.99.30.11:8443/realms/service.heim.lan |
| Client ID | PegaProx |
| Client Secret | lokal aus Keycloak Credentials einsetzen |
| Scopes | openid profile email |
| Redirect URI | https://9.99.30.13:5000/oidc/callback |
| JWT-Signaturprüfung | aktiviert |
| Skip SSL verification | OFF, abschließend überprüfen |
| Allow private IP | nur bei beabsichtigtem internem IdP und konkreter SSRF-Blockierung erforderlich; finaler Chat-Wert unbekannt |
| Auto-create users on first login | ON |
| Default Role (no group match) | Viewer |
In das Issuer-Feld gehört weder die Discovery-URL noch der /auth-Endpunkt. Save OIDC Settings, anschließend OIDC-Test. Discovery muss erfolgreich sein und der Authorization-Endpunkt auf /protocol/openid-connect/auth enden. Bei deaktivierter Discovery verwendete die untersuchte Version einen falschen /authorize-Fallback.
5. Gruppen, Client Scope und Mapper
Im Realm unter Groups → Create group anlegen:
pegaprox-admins
pegaprox-users
pegaprox-viewers
Unter Users → Benutzer → Groups → Join Group zuweisen. Im Chat war svc_cm_admin das Beispiel für die Mitgliedschaft in pegaprox-admins; der Name allein verleiht keine Rechte und meint hier einen interaktiv anmeldenden Benutzer, keinen Client-Credentials-Service-Account.
Client Scopes → Create client scope: Name pegaprox-groups, Protocol OpenID Connect. Unter Mappers → Configure a new mapper → Group Membership:
| Einstellung | Wert |
|---|---|
| Name | groups |
| Token Claim Name | groups |
| Full group path | OFF |
| Add to ID token | ON |
| Add to access token | ON |
| Add to userinfo | ON |
Danach Clients → PegaProx → Client scopes → Add client scope: pegaprox-groups als Default zuweisen. Deshalb muss der Scope nicht zusätzlich im angeforderten openid profile email stehen. Die Scope-JSON-Datei bildet diese Mapper-Einstellungen ab; Import allein ersetzt weder Client-Zuweisung noch Gruppenmitgliedschaften. Grundlagen: Keycloak Client Scopes und Mapper.
Unter Clients → PegaProx → Client scopes → Evaluate einen Gruppenbenutzer wählen. Im Generated ID Token muss stehen:
{"groups": ["pegaprox-admins"]}
Kein führender Slash und keine Gruppen-UUID. Ein Realm-Rollen-Claim unter realm_access.roles ersetzt diesen Gruppen-Claim nicht. Nach Änderungen neue Tokens durch erneute Anmeldung erzeugen.
6. PegaProx Group → Role Mapping
Auf derselben OIDC-Seite nach unten zu Group → Role Mapping. Im Feld GroupName den Namen eingeben, rechts die Rolle wählen; weitere Zeilen über + Add Mapping:
| GroupName | Rolle |
|---|---|
| pegaprox-admins | Administrator |
| pegaprox-users | User |
| pegaprox-viewers | Viewer |
Default Role (no group match): Viewer, Auto-create users on first login: ON, anschließend Save OIDC Settings.
Die früher im Chat vermuteten Felder „Admin Group ID“ usw. sind nicht die bestätigte UI-Anleitung. Die bestätigte Oberfläche verwendet die obige Mapping-Tabelle. Der gepostete Code unterstützt zusätzlich eingebaute Gruppenfelder und gewichtet Administrator vor User vor Viewer; er normalisiert Groß-/Kleinschreibung, entfernt aber keinen führenden Slash aus Claim-Werten. Für einfache Nachvollziehbarkeit genau die obigen Gruppennamen nutzen.
7. Login und Abnahme
PegaProx vollständig abmelden, bei Bedarf ein separates Browserprofil verwenden, dann Sign in with OIDC. Keycloak-Anmeldung durchführen; Rückkehr zur Callback-URI und Anmeldung in PegaProx prüfen. Den Account svc_cm_admin (Beispiel) als Administrator erwarten. Die Testmatrix deckt weitere Rollen ab.
Bestehende Benutzer zuerst erneut anmelden und die effektive Rolle kontrollieren. Der Codeauszug enthält einen Aktualisierungspfad für Benutzer; welche Attribute aktualisiert werden, wurde nicht vollständig gezeigt. Deshalb ist Löschen kein allgemeiner Pflichtschritt. Der Chat schlug die Neuanlage eines falsch provisionierten Accounts vor, belegt deren Ausführung aber nicht. Nur falls erforderlich, nach Prüfung von Zuordnungen und Daten sowie mit verfügbarem lokalem Admin den betroffenen PegaProx-Account gezielt neu provisionieren; nicht den Keycloak-Benutzer löschen.
8. Finaler funktionierender Zusammenhang
Keycloak Realm service.heim.lan / Client PegaProx
→ Discovery liefert Keycloak-Endpunkte
→ Authorization Code + PKCE S256
→ Callback https://9.99.30.13:5000/oidc/callback
→ groups enthält pegaprox-admins
→ PegaProx Group → Role Mapping
→ Administrator
Dieser Ablauf wurde vom Benutzer als funktionierend bestätigt. Viewer als Standard und TLS-Prüfung ON sind die dokumentierte Zielkonfiguration; ein vollständiger abschließender Konfigurationsexport oder Sicherheits-Test liegt nicht vor. Die Vorlagen sind ohne Geheimnisse und keine Sicherung der laufenden Installation. pegaprox-oidc.example.json ist ausdrücklich eine lesbare Sollwertliste, kein zugesichertes Import-/API-Format.
9. In Git übernehmen
ZIP entpacken, in den entpackten Ordner wechseln:
git init
git add README.md docs example-configs scripts .gitignore
git diff --cached --check
git diff --cached
git commit -m "docs: document PegaProx Keycloak OIDC setup"
Vor dem Commit lokale Anpassungen auf Secrets prüfen. Ein Remote-Repository wurde nicht erstellt oder veröffentlicht. .gitignore schützt nur passende unversionierte Dateien; niemals echte Secrets in die versionierten Vorlagen eintragen.