This commit is contained in:
Madzone
2026-09-10 09:14:19 +02:00
parent efba066b51
commit ce5e389abd
23 changed files with 639 additions and 0 deletions
+92
View File
@@ -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.
+36
View File
@@ -0,0 +1,36 @@
# Tests und Abnahmeprotokoll
## Historisch belegt
- curl: Zertifikatsprüfung erfolgreich, Discovery HTTP 200.
- requests: HTTP 200, passender Issuer sowie Authorization-/JWKS-Endpunkte.
- requests und certifi zeigten auf `/etc/ssl/certs/ca-certificates.crt`.
- Browser nutzte zunächst den falschen `/authorize`-Pfad und erhielt „Page not found“.
- Nach Neustart-/TLS-Test-Vorschlag: Benutzer meldete „ok ht geholfen“.
- Geteilte Claims enthielten `groups: ["pegaprox-admins"]`.
- Nach Anleitung zum Group→Role Mapping: Benutzer meldete „es geht jatzt“.
Nicht einzeln nachgewiesen: finaler TLS-Schalter, erfolgte CA-Installation, tatsächlich ausgeführter Neustart, Benutzerlöschung, alle drei Rollentests, Logout sowie Versionsnummern.
## Wiederholbare Abnahme
| Test | Erwartung | Ergebnis / Datum |
|---|---|---|
| Discovery per curl ohne -k | TLS gültig, HTTP 200 | offen |
| Python im Dienstkontext | HTTP 200, exakter Issuer | offen |
| PegaProx-OIDC-Test | Discovery erfolgreich, korrekte auth/JWKS URLs | offen |
| TLS-Schalter | Skip SSL verification OFF | offen |
| JWT-Prüfung | aktiviert | offen |
| Token Evaluate | groups als Array ohne führenden Slash | offen |
| Frischer Admin-Login | Administrator | offen |
| Frischer User-Login | User; keine Admin-Funktionen | offen |
| Frischer Viewer-Login | Viewer; keine Schreibrechte | offen |
| Ohne passende Gruppe | Viewer | offen |
| Admin- und User-Gruppe zusammen | Administrator gemäß untersuchtem Code | offen |
| Bestehender Benutzer nach Gruppenänderung | tatsächliche Rollenaktualisierung prüfen | offen |
Viewer als Default bedeutet, dass ein Benutzer ohne passende Gruppe grundsätzlich noch Leserechte erhalten kann. Falls gar kein Zugriff gewünscht ist, muss das gesondert konfiguriert und getestet werden.
Ein HTTP 400 am Authorization-Endpunkt ohne vollständige Login-Parameter kann dessen Erreichbarkeit zeigen, beweist aber keinen erfolgreichen Login. Erst der vollständige Browser-Flow prüft Client Secret, Callback, Tokenverarbeitung und effektive Rollen gemeinsam. Ein decodiertes JWT allein beweist keine gültige Signatur; Evaluate ist ein Claim-Konfigurationstest.
Keine echten Tokens, Secrets, Cookies oder vollständigen Benutzerprofile in dieses Protokoll aufnehmen. Prüfungen der gelieferten Dateien sind keine Live-Tests der internen Installation.