New
This commit is contained in:
@@ -0,0 +1,92 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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](https://requests.readthedocs.io/en/stable/user/advanced/#ssl-cert-verification).
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
/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:
|
||||
|
||||
```bash
|
||||
/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.
|
||||
Reference in New Issue
Block a user