Files
syno-scripts/PegaProx-IDM
2026-09-10 09:14:19 +02:00
..
New
2026-09-10 09:14:19 +02:00
New
2026-09-10 09:14:19 +02:00
New
2026-09-10 09:14:19 +02:00
New
2026-09-10 09:14:19 +02:00
New
2026-09-10 09:14:19 +02:00

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.