- Go 91.6%
- Shell 7.6%
- Dockerfile 0.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
ci / test (push) Successful in 1m34s
Reviewed-on: #2 Reviewed-by: jochen <jochen@bocc.de> |
||
| .forgejo/workflows | ||
| deploy | ||
| internal | ||
| .containerignore | ||
| .gitignore | ||
| Containerfile | ||
| go.mod | ||
| main.go | ||
| README.md | ||
mcp-auth-sidecar
Kleiner Sidecar, der einen bestehenden MCP-Server bzw. ein MCP-Gateway für die MCP-Autorisierung (OAuth 2.1) fit macht, ohne einen vollwertigen Identity-Aware-Proxy wie Pomerium. Als Authorization Server dient Keycloak, davor kann eine WAF wie FortiWeb stehen.
Ein Go-Binary ohne Fremdabhängigkeiten (nur Standardbibliothek), Container ca. 10 MB, keine Datenbank.
Was er liefert
| Endpunkt | Zweck |
|---|---|
/.well-known/oauth-protected-resource und /.well-known/oauth-protected-resource/<pfad> |
Protected Resource Metadata (RFC 9728), zeigt auf Keycloak als Authorization Server |
/.well-known/oauth-authorization-server, …/oauth-authorization-server/<issuer-pfad>, …/openid-configuration/<issuer-pfad> |
Spiegel der Keycloak-Discovery (RFC 8414), gecacht. Hilft älteren MCP-Clients und Clients, die „path insertion“ nutzen |
| alle übrigen Pfade (Proxy-Modus) | Bearer-Token prüfen, bei Erfolg an das Upstream weiterreichen, sonst spec-konform 401 mit WWW-Authenticate: Bearer resource_metadata="…" |
/-/healthz, /-/readyz |
Liveness bzw. Readiness (bereit, sobald JWKS geladen) |
Ablauf
sequenceDiagram
participant C as MCP-Client (z. B. Claude)
participant F as FortiWeb
participant S as mcp-auth-sidecar
participant G as MCP-Gateway
participant K as Keycloak
C->>F: POST /mcp (ohne Token)
F->>S: weiter
S-->>C: 401 WWW-Authenticate: resource_metadata=…
C->>S: GET /.well-known/oauth-protected-resource/mcp
S-->>C: authorization_servers: [Keycloak-Realm]
C->>K: Discovery, Dynamic Client Registration, Login (PKCE)
K-->>C: Access Token (aud = MCP-Ressource)
C->>F: POST /mcp, Authorization: Bearer …
F->>S: weiter
S->>S: Signatur (JWKS), iss, aud, exp, typ, Scopes prüfen
S->>G: weiter mit X-Auth-Subject/Email/…
G-->>C: Antwort / SSE-Stream (ungepuffert)
Betriebsarten
proxy (Standard): Der Sidecar sitzt vor dem Gateway und prüft selbst.
Er streamt SSE und Streamable HTTP ohne Pufferung und reicht Mcp-Session-Id
durch. Eingehende Header mit dem Identitäts-Präfix (X-Auth-) werden immer
entfernt, damit sie nicht gefälscht werden können.
metadata: Nur die /.well-known/-Endpunkte. Die WAF routet diese Pfade
zum Sidecar und prüft Tokens selbst. Das funktioniert nur, wenn die WAF bei
fehlendem oder ungültigem Token ein echtes 401 mit korrektem
WWW-Authenticate-Header liefert. Sonst startet der Client den OAuth-Flow nie.
Konfiguration
Alle Variablen haben das Präfix MCPAUTH_. Vorlage: deploy/quadlet/sidecar.env.example.
| Variable | Standard | Beschreibung |
|---|---|---|
RESOURCE_URL |
– (Pflicht) | Öffentliche URL des MCP-Endpunkts, z. B. https://mcp.example.de/mcp |
ISSUER_URL |
– (Pflicht) | Keycloak-Realm, z. B. https://kc.example.de/realms/mcp |
UPSTREAM_URL |
– (Pflicht im Proxy-Modus) | MCP-Gateway, z. B. http://mcp-gateway:3000 |
MODE |
proxy |
proxy oder metadata |
LISTEN_ADDR |
:8080 |
Listen-Adresse |
AUDIENCE |
RESOURCE_URL |
Erlaubte aud-Werte (Komma/Leerzeichen-getrennt) |
REQUIRED_SCOPES |
– | Pflicht-Scopes, sonst 403 insufficient_scope |
SCOPES_SUPPORTED |
REQUIRED_SCOPES |
Für die Metadaten |
RESOURCE_NAME, RESOURCE_DOCUMENTATION |
– | Optionale Metadatenfelder |
JWKS_URL |
aus Discovery | Nur setzen, wenn abweichend |
ALLOWED_ALGS |
RS*, PS*, ES*, EdDSA | Nur asymmetrische Verfahren möglich |
CLOCK_SKEW |
60s |
Toleranz für exp/nbf/iat |
JWKS_REFRESH_INTERVAL |
15m |
Periodisches Neuladen |
JWKS_MIN_REFRESH_INTERVAL |
30s |
Rate-Limit fürs Nachladen bei unbekannter kid (Schlüsselrotation) |
DISCOVERY_CACHE_TTL |
10m |
Cache für Keycloak-Discovery |
HTTP_TIMEOUT |
10s |
Timeout für Keycloak-Abrufe |
SERVE_AS_METADATA |
true |
AS-Metadaten spiegeln |
FORWARD_IDENTITY |
true |
X-Auth-Subject, -Email, -Username, -Client-Id, -Scopes setzen |
HEADER_PREFIX |
X-Auth- |
Präfix der Identitäts-Header |
STRIP_AUTHORIZATION |
false |
Token nicht ans Upstream weitergeben |
PRESERVE_HOST |
false |
Original-Host ans Upstream |
TRUST_FORWARDED_HEADERS |
false |
X-Forwarded-* vom vorgelagerten Proxy übernehmen (hinter FortiWeb: true) |
ALLOW_PREFLIGHT |
true |
CORS-Preflights ohne Token durchlassen |
REQUIRE_BEARER_TYP |
true |
Keycloak-Claim typ muss Bearer sein (blockt ID-/Refresh-Tokens) |
ALLOW_INSECURE_HTTP |
false |
http:// für Resource/Issuer erlauben (nur Tests) |
INTROSPECTION |
false |
Tokens zusätzlich per Introspection (RFC 7662) bei Keycloak prüfen, nur im Proxy-Modus |
INTROSPECTION_CLIENT_ID |
– (Pflicht bei Introspection) | Vertraulicher Keycloak-Client, z. B. mcp-sidecar |
INTROSPECTION_CLIENT_SECRET oder …_SECRET_FILE |
– (eins davon Pflicht) | Client-Secret; besser als Datei bzw. Podman-Secret |
INTROSPECTION_URL |
aus Discovery | Nur setzen, wenn abweichend |
INTROSPECTION_CACHE_TTL |
15s |
Cache je Token; zugleich maximale Verzögerung eines Widerrufs. 0 = kein Cache |
LOG_LEVEL, LOG_FORMAT |
info, json |
Logging |
Token Introspection (optional)
Standardmäßig prüft der Sidecar Tokens nur lokal gegen das JWKS von Keycloak. Das kommt ohne Netzwerkaufruf pro Request aus, erkennt aber keinen Widerruf: Ein gesperrter Nutzer behält Zugriff, bis sein Access Token abläuft.
Mit INTROSPECTION=true fragt der Sidecar nach der lokalen Prüfung zusätzlich
den Introspection-Endpunkt von Keycloak. Damit wirken Sperren und beendete
Sessions nach spätestens INTROSPECTION_CACHE_TTL.
- Reihenfolge: Erst lokal, dann Introspection. Ungültige oder fremde Tokens erzeugen so keine Last bei Keycloak.
- Cache: Antworten werden pro Token (SHA-256 als Schlüssel) höchstens
INTROSPECTION_CACHE_TTLlang wiederverwendet, aktive nie überexphinaus. - Fail closed: Ist Keycloak nicht erreichbar oder lehnt die Client-Zugangsdaten ab, antwortet der Sidecar mit
503undRetry-After, nicht mit401. So startet der Client keinen unnötigen neuen Login, und Fehlkonfigurationen fallen im Log auf. - Audience-Prüfung in Keycloak: Neuere Keycloak-Versionen beantworten Introspection nur dann mit
active: true, wenn der prüfende Client imauddes Tokens steht. Die Optionen „Allow token introspection without audience check“ (pro Client oder serverweit) gelten als veraltet.setup-realm.shlöst das mitINTROSPECTION_CLIENT=mcp-sidecarsauber: Es legt den vertraulichen Client ohne Login-Flows an und nimmt ihn per zweitem Audience-Mapper im Scopemcpin jedes Token auf. - Umstellung: Erst den Mapper anlegen, dann Introspection einschalten. Bereits ausgestellte Tokens ohne den Client im
audgelten sonst als inaktiv; Claude holt sich per Refresh ein neues. - Lightweight Access Tokens in Keycloak für MCP-Clients nicht einschalten: Dann fehlen die Claims im Token, und die lokale Prüfung schlägt fehl.
Keycloak
deploy/keycloak/setup-realm.sh richtet einen
eigenen Realm per kcadm.sh ein. Das Skript ist erneut ausführbar.
- Client Scope
mcpmit Audience-Mapper aufMCP_RESOURCE_URL, als Realm-Default für neue Clients. - Anonyme Dynamic Client Registration nur für Redirect-URIs auf vertrauenswürdigen Hosts (Standard
claude.ai, Callbackhttps://claude.ai/api/mcp/auth_callback). Die übrigen Keycloak-Default-Policies (Consent Required, Max Clients, Full Scope Disabled) bleiben aktiv. - PKCE S256 für alle Clients des Realms per Client Policy. Ersetzt vorhandene Client Policies des Realms.
- Optional mit
INTROSPECTION_CLIENT=mcp-sidecar: vertraulicher Client für die Introspection samt Audience-Mapper (siehe oben). Das Skript gibt den Befehl zum Abrufen des Secrets aus, nicht das Secret selbst.
Den eigentlichen Login (AD/LDAP, Entra ID, SAML-IdP) bindet man im Realm als User Federation oder Identity Provider an. Keycloak übernimmt dann nur den MCP-spezifischen OAuth-Teil.
FortiWeb davor
- Server-Pool auf den Sidecar zeigen lassen. Die
/.well-known/-Pfade müssen ohne Authentisierung erreichbar sein. - Für SSE: keine Response-Pufferung bzw. Body-Inspection auf
text/event-stream, großzügige Idle-Timeouts. - Header
Authorization,Mcp-Session-IdundWWW-Authenticateunverändert durchreichen. - Optional für Claude-Connectoren: IP-Allowlist auf die veröffentlichten Egress-IPs von Anthropic.
Deployment mit Podman/Quadlet
podman build -t git.bocc.de/claude/mcp-auth-sidecar:0.1.0 --build-arg VERSION=0.1.0 .
podman push git.bocc.de/claude/mcp-auth-sidecar:0.1.0
sudo install -d -m 700 /etc/mcp-auth-sidecar
sudo install -m 600 deploy/quadlet/sidecar.env.example /etc/mcp-auth-sidecar/sidecar.env # anpassen
sudo cp deploy/quadlet/mcp.network deploy/quadlet/mcp-auth-sidecar.container /etc/containers/systemd/
sudo systemctl daemon-reload && sudo systemctl start mcp-auth-sidecar
Das bestehende Gateway kommt mit Network=mcp.network ins selbe Netz und
veröffentlicht selbst keinen Port mehr. Es ist dann nur noch über den Sidecar erreichbar.
Entwicklung
go vet ./...
go test -race ./...
go build -o mcp-auth-sidecar .
Tests decken ab: Signaturprüfung (RS256, PS256, ES256, EdDSA), Ablehnung von
alg=none, manipulierten Payloads, falschen iss/aud, abgelaufenen Tokens und
ID-Tokens, schwachen oder ungültigen JWKs, Schlüsselrotation mit Rate-Limit,
401/403-Challenges, Header-Spoofing, CORS-Preflight und ungepuffertes SSE.
Für die Introspection zusätzlich: Cache und Begrenzung auf exp, widerrufene
Tokens, keine Abfrage für lokal ungültige Tokens, 503 bei Ausfall oder
falschen Client-Zugangsdaten, Form-Kodierung von Client-ID und Secret.
Sicherheitshinweise
- Keine Token-Durchreichung an Dritt-APIs: Das Gateway ist selbst die Ressource. Braucht es weitere APIs, holt es eigene Tokens (z. B. per Token Exchange).
- Tokens werden nie geloggt. Abgelehnte Tokens werden mit Grund, Remote-Adresse und Pfad auf
infoprotokolliert. - Das Introspection-Secret nie ins Env-File schreiben, sondern als Podman-Secret mounten (
INTROSPECTION_CLIENT_SECRET_FILE). - Upstream-Port nicht direkt veröffentlichen, sonst lässt sich der Sidecar umgehen.
Offen / zu prüfen
setup-realm.shgegen die eingesetzte Keycloak-Version testen. Admin-API-Details, z. B. der Client-Policy-Conditionany-client, können sich zwischen Versionen unterscheiden.- Basis-Images im
Containerfileper Digest pinnen. - Runner-Label in
.forgejo/workflows/ci.ymlan die eigene Runner-Konfiguration anpassen. - Neuere MCP-Spezifikationen erlauben statt DCR auch Client-ID-Metadata-Dokumente. Ob Keycloak und die genutzten Clients das bereits unterstützen, ist zu prüfen. Am Sidecar ändert das nichts.