Files
2026-09-10 09:14:19 +02:00

6.5 KiB

Troubleshooting

Alle Adressen sind Beispielwerte aus der Unterhaltung. Befehle im tatsächlichen PegaProx-System ausführen. Dienstneustarts unterbrechen laufende Sitzungen möglicherweise kurz.

Fehlerbilder

Symptom Einordnung Maßnahme
CERTIFICATE_VERIFY_FAILED / self-signed certificate in certificate chain CA-Vertrauen oder Kette im anfragenden Prozess fehlt CA, Kette, SAN und Prozessumgebung prüfen
Discovery doc not reachable, danach /authorize 404 PegaProx fällt auf generische Endpunkte zurück Discovery/TLS beheben, nicht Issuer um /protocol/openid-connect erweitern
/realms/service.heim.lan/.well-known/jwks.json schlägt fehl Ebenfalls generischer Fallback Discovery muss /protocol/openid-connect/certs liefern
curl/Python 200, PegaProx weiterhin TLS-Fehler Shell und Dienst können verschiedene Umgebungen haben Interpreter, Dienstbenutzer, CA-Variablen prüfen; Dienst neu starten
invalid_redirect_uri Callback stimmt nicht exakt überein Schema, IP/Host, Port, Pfad und Slash mit Client vergleichen
invalid_client Client ID, Secret oder Client-Authentifizierung falsch PegaProx ID und aktuelles Secret mit Client Credentials abgleichen
groups fehlt Mapper, Scope-Zuweisung oder Mitgliedschaft fehlt Evaluate prüfen, Scope Default, frische Tokens
/pegaprox-admins statt pegaprox-admins Full group path aktiv Mapper auf OFF, neu anmelden
Gruppe korrekt, aber Benutzer statt Administrator PegaProx-Mapping fehlt/falsch oder bestehende Provisionierung GroupName und Rolle speichern; erneute Anmeldung
SSRF guard rejected / private IP URL-Schutz blockiert Ziel Issuer prüfen; gezielte Allow-private-IP-Option für beabsichtigten IdP
kcadm invalid_grant Anmeldung der Admin CLI fehlgeschlagen Anmelde-Realm, Passwort, Kontostatus, Required Actions prüfen

TLS systematisch eingrenzen

curl -v 'https://9.99.30.11:8443/realms/service.heim.lan/.well-known/openid-configuration'
/usr/bin/python3 -c 'import requests, certifi, ssl; print(requests.certs.where()); print(certifi.where()); print(ssl.get_default_verify_paths())'
systemctl show pegaprox --property=User --property=ExecStart --property=MainPID

Im Chat: CA-Bundle /etc/ssl/certs/ca-certificates.crt, Zertifikat-CN keycloak.service.heim.lan, Aussteller HEIMLAN_SubCA, IP-SAN passte. Der CN allein wäre für IP-Zugriff nicht ausreichend. Das gezeigte Zertifikat galt vom 18.07.2026 bis 17.07.2028; das ist historischer Befund, keine Aussage über das heute installierte Zertifikat.

Mit dem Diagnose-Skript aus dem Repo und einem für den Dienstbenutzer lesbaren absoluten Pfad:

sudo -u pegaprox /usr/bin/python3 /pfad/zum/repo/scripts/check-discovery.py
# Ohne sudo, als root:
runuser -u pegaprox -- /usr/bin/python3 /pfad/zum/repo/scripts/check-discovery.py

Das prüft Benutzer und Interpreter, übernimmt aber nicht automatisch die systemd-Umgebung. Dienstdatei und Drop-ins lokal auf CA-Pfade prüfen; keine vollständigen Umgebungs- oder Konfigurationsdumps veröffentlichen, da diese Secrets enthalten können.

Vergleich mit explizitem Bundle:

REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt \
  /usr/bin/python3 scripts/check-discovery.py

Funktioniert nur das, kann die mitgelieferte example-configs/pegaprox-ca.conf.example als systemd-Drop-in dienen. Vorhandene Overrides prüfen und ergänzen, nicht überschreiben:

sudo systemctl edit pegaprox
# Inhalt der Beispiel-Datei im Editor ergänzen und speichern.
sudo systemctl daemon-reload
sudo systemctl restart pegaprox
sudo systemctl status pegaprox --no-pager

Requests unterstützt REQUESTS_CA_BUNDLE; SSL_CERT_FILE ist zusätzlich für Python/OpenSSL-Verbraucher vorgesehen, die es berücksichtigen. Ein Shell-export ändert keinen bereits laufenden systemd-Dienst. Siehe Requests TLS-Dokumentation.

Danach PegaProx-OIDC-Test mit Skip SSL verification OFF. Ein kurzer unautorisierter Discovery-Abruf mit curl -k kann TLS als Ursache eingrenzen, validiert aber keine Identität. Den Login nicht als TLS-erfolgreich bewerten, solange die Zertifikatsprüfung ausgeschaltet ist. JWT-Prüfung bleibt aktiviert.

Fallback und Cache

Der gepostete Code in /usr/lib/pegaprox/pegaprox/utils/oidc.py ruft Discovery per requests auf. Bei TLS-/HTTP-/JSON-Fehlern konstruiert er <authority>/authorize, /token, /.well-known/jwks.json und /userinfo. Diese Vermutungen passen nicht zu den gezeigten Keycloak-Endpunkten. Erfolgreiche Discovery-Daten werden dort bis zu 3600 Sekunden gecacht. Ein Dienstneustart setzt den Prozesszustand zurück; anschließend erneut testen.

Frühere Chat-Vermutungen über einen nachgewiesenen Codefehler oder ein separates certifi-Bundle wurden nicht bestätigt. Keine pauschale Zeichenersetzung in oidc.py durchführen: Sie verdeckt die eigentliche Discovery-Ursache und ist nicht der dokumentierte finale Fix.

Admin CLI: Anmelde-Realm und Ziel-Realm unterscheiden

Auf dem Keycloak-System, Passwort interaktiv eingeben:

/opt/keycloak/bin/kcadm.sh config credentials \
  --server 'https://9.99.30.11:8443' \
  --realm master --user '<MASTER_ADMIN>'
/opt/keycloak/bin/kcadm.sh get clients -r 'service.heim.lan' \
  -q clientId=PegaProx --fields id,clientId

Falls der berechtigte Administrator stattdessen im Realm service.heim.lan liegt, diesen Realm bei config credentials --realm angeben. Der Ziel-Realm der späteren Operationen bleibt -r service.heim.lan. Ein gleichnamiger Benutzer in beiden Realms ist nicht dieselbe Identität. Das im Chat versuchte madzone im Realm master scheiterte mit invalid_grant; ein späterer CLI-Erfolg ist nicht belegt. Erfolgreiche Anmeldung allein beweist zudem noch keine administrativen Rechte.

Optionale Erstellung einer noch nicht vorhandenen Gruppe:

/opt/keycloak/bin/kcadm.sh get groups -r 'service.heim.lan' \
  -q search=pegaprox-admins --fields id,name
# Nur anlegen, falls die exakte Gruppe noch nicht existiert:
/opt/keycloak/bin/kcadm.sh create groups -r 'service.heim.lan' \
  -s name=pegaprox-admins

Analog für users/viewers. Kein pauschales || true: Es würde Berechtigungs- und Netzwerkfehler verschlucken. Die CLI kann eine eigene Java-Truststore-Konfiguration benötigen; ein erfolgreiches Python-TLS-Ergebnis gilt nicht automatisch für Java. CLI-Konfigurationsdateien mit Tokens außerhalb dieses Repos halten. Vollständige Gruppen-/Mapper-Automatisierung war im Chat nur angeboten, nicht ausgeführt.