Optionale Token Introspection (RFC 7662) für schnellen Widerruf #2

Merged
jochen merged 4 commits from feature/token-introspection into main 2026-11-13 19:32:03 +00:00
Owner

Zweck

Bisher prüft der Sidecar Tokens nur lokal gegen das JWKS. Ein gesperrter Nutzer behält Zugriff, bis sein Access Token abläuft. Mit MCPAUTH_INTROSPECTION=true fragt der Sidecar zusätzlich den Introspection-Endpunkt von Keycloak, ein Widerruf wirkt dann nach spätestens INTROSPECTION_CACHE_TTL (Standard 15 s). Standardmäßig bleibt die Introspection aus, das Verhalten ändert sich ohne Konfiguration nicht.

Umsetzung

  • Reihenfolge: erst lokale JWT-Prüfung, dann Introspection. Ungültige Tokens erzeugen keine Last bei Keycloak.
  • Cache je Token (SHA-256 als Schlüssel), aktive Antworten nie über exp hinaus, Größe begrenzt.
  • Fail closed: Keycloak nicht erreichbar oder Client-Zugangsdaten falsch → 503 + Retry-After, kein 401 (sonst startet Claude unnötig einen neuen Login).
  • Vertraulicher Client mit Basic Auth, Form-Kodierung nach RFC 6749 2.3.1. Secret per Env oder besser als Datei (…_SECRET_FILE, Podman-Secret).
  • Keycloak-Audience-Prüfung: Neuere Versionen beantworten Introspection nur, wenn der prüfende Client im aud steht. setup-realm.sh legt mit INTROSPECTION_CLIENT=mcp-sidecar den Client ohne Login-Flows an und nimmt ihn per zweitem Audience-Mapper in den Scope mcp auf. Die veralteten Optionen „without audience check“ werden nicht gebraucht.

Getestet

Lokal mit Go 1.24: gofmt, go vet, go test -race grün, statischer Build ok. Neue Tests: Cache und exp-Grenze, TTL 0, Cache-Obergrenze, widerrufenes Token → 401, lokal ungültiges Token ohne Introspection-Aufruf, Ausfall und falsches Secret → 503, keine Zwischenspeicherung von Fehlern, Config-Validierung. Der Tree-Hash des Branches ist gegen den lokal getesteten Stand abgeglichen.

Nicht getestet / offen

  • Der neue Teil von setup-realm.sh lief noch nicht gegen ein echtes Keycloak, bitte zuerst im Test-Realm.
  • Umstellung: erst Mapper anlegen, dann Introspection einschalten. Bestehende Tokens ohne den Client im aud gelten sonst als inaktiv, bis Claude sie per Refresh erneuert.
  • Die Commit-Nachricht von 5496fb8 nennt Keycloak-Skript und README, die erst in 77fe8a4 folgen. Beim Mergen am besten squashen.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vh6imk3Z4tM1rGkQ5W2xQA

## Zweck Bisher prüft der Sidecar Tokens nur lokal gegen das JWKS. Ein gesperrter Nutzer behält Zugriff, bis sein Access Token abläuft. Mit `MCPAUTH_INTROSPECTION=true` fragt der Sidecar zusätzlich den Introspection-Endpunkt von Keycloak, ein Widerruf wirkt dann nach spätestens `INTROSPECTION_CACHE_TTL` (Standard 15 s). Standardmäßig bleibt die Introspection aus, das Verhalten ändert sich ohne Konfiguration nicht. ## Umsetzung - **Reihenfolge:** erst lokale JWT-Prüfung, dann Introspection. Ungültige Tokens erzeugen keine Last bei Keycloak. - **Cache** je Token (SHA-256 als Schlüssel), aktive Antworten nie über `exp` hinaus, Größe begrenzt. - **Fail closed:** Keycloak nicht erreichbar oder Client-Zugangsdaten falsch → `503` + `Retry-After`, kein `401` (sonst startet Claude unnötig einen neuen Login). - **Vertraulicher Client** mit Basic Auth, Form-Kodierung nach RFC 6749 2.3.1. Secret per Env oder besser als Datei (`…_SECRET_FILE`, Podman-Secret). - **Keycloak-Audience-Prüfung:** Neuere Versionen beantworten Introspection nur, wenn der prüfende Client im `aud` steht. `setup-realm.sh` legt mit `INTROSPECTION_CLIENT=mcp-sidecar` den Client ohne Login-Flows an und nimmt ihn per zweitem Audience-Mapper in den Scope `mcp` auf. Die veralteten Optionen „without audience check“ werden nicht gebraucht. ## Getestet Lokal mit Go 1.24: `gofmt`, `go vet`, `go test -race` grün, statischer Build ok. Neue Tests: Cache und `exp`-Grenze, TTL 0, Cache-Obergrenze, widerrufenes Token → 401, lokal ungültiges Token ohne Introspection-Aufruf, Ausfall und falsches Secret → 503, keine Zwischenspeicherung von Fehlern, Config-Validierung. Der Tree-Hash des Branches ist gegen den lokal getesteten Stand abgeglichen. ## Nicht getestet / offen - Der neue Teil von `setup-realm.sh` lief noch **nicht gegen ein echtes Keycloak**, bitte zuerst im Test-Realm. - Umstellung: erst Mapper anlegen, dann Introspection einschalten. Bestehende Tokens ohne den Client im `aud` gelten sonst als inaktiv, bis Claude sie per Refresh erneuert. - Die Commit-Nachricht von 5496fb8 nennt Keycloak-Skript und README, die erst in 77fe8a4 folgen. Beim Mergen am besten squashen. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01Vh6imk3Z4tM1rGkQ5W2xQA
- Introspector mit vertraulichem Client, Form-Kodierung nach RFC 6749 2.3.1
- Erst lokale JWT-Prüfung, dann Introspection: ungültige Tokens erzeugen keine Last
- Cache je Token (SHA-256), höchstens INTROSPECTION_CACHE_TTL, aktiv nie über exp
- Fail closed mit 503 + Retry-After bei Ausfall oder falschen Zugangsdaten
- Secret per Env oder Datei (Podman-Secret), Config-Validierung
- Unit- und Integrationstests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh6imk3Z4tM1rGkQ5W2xQA
- MCPAUTH_INTROSPECTION*, Secret per Env oder Datei, Validierung
- 503 + Retry-After statt 401 bei nicht erreichbarem Authorization Server
- Integrationstests mit Fake-Introspection-Endpunkt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh6imk3Z4tM1rGkQ5W2xQA
- setup-realm.sh: optionaler Client INTROSPECTION_CLIENT samt Audience-Mapper,
  passend zur Audience-Prüfung neuerer Keycloak-Versionen, ohne veraltete
  "introspection without audience check"-Optionen
- Quadlet: Secret als Podman-Secret, Env-Vorlage ergänzt
- README: Abschnitt Token Introspection, Konfigurationstabelle

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh6imk3Z4tM1rGkQ5W2xQA
setup-realm.sh: Introspection-Client mit Audience-Mapper; README
All checks were successful
ci / test (pull_request) Successful in 1m36s
77fe8a4943
- Optionaler vertraulicher Client INTROSPECTION_CLIENT ohne Login-Flows
- Zweiter Audience-Mapper im Scope mcp, damit Keycloak die Introspection
  trotz Audience-Prüfung beantwortet (keine veralteten Ausnahme-Optionen)
- README: Abschnitt Token Introspection, Konfigurationstabelle, Hinweise

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh6imk3Z4tM1rGkQ5W2xQA
jochen approved these changes 2026-11-13 19:31:54 +00:00
jochen merged commit 8fd6311e82 into main 2026-11-13 19:32:03 +00:00
jochen deleted branch feature/token-introspection 2026-11-13 19:32:03 +00:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
claude/mcp-auth-sidecar!2
No description provided.