Keycloak Realm Inspector

Ein MCP-Server, der ausschließlich eine durch OAuth 2.0 geschützte Ressource ist, für einen KeyConf-2026-Vortrag über Client-ID-Metadaten-Dokumente (draft-ietf-oauth-client-id-metadata-document-02).

Er stellt nichts aus — kein /authorize, kein /token, kein Client-Secret. Keycloak stellt Tokens aus; dieser Server validiert sie gegen Keycloaks JWKS, stellt die RFC-9728-Discovery bereit und bietet drei Werkzeuge an, die CIMD von innerhalb des Ressourcenservers sichtbar machen.

Drei Parteien, bewusst voneinander getrennt

Dieser Server hostet, liest oder ruft das Metadaten-Dokument des Clients nicht ab. Es gibt keine /client-metadata.json-Route und keine lokale Kopie. Keycloak ruft diese URL während /authorize über das Netzwerk ab. In dieser Codebasis erscheint die URL immer nur als opaker String, der im azp-Claim ankommt — genau das ist der ganze Sinn der Demo, und der Grund, warum das Dokument von einem separaten Prozess auf einem separaten Port bereitgestellt wird.

Related MCP server: mcpauth

Ausführen

Es wird davon ausgegangen, dass Keycloak läuft, der Realm erstellt und die CIMD-Client-Policy bereits angewendet wurde. Der Client, sein Metadaten-Dokument und der Token-Helper befinden sich neben diesem Repository in ../cimd-demo/auth-server/.

# terminal 1 — the client's document. Its own party, its own port.
cd ../cimd-demo/auth-server && python -m http.server 9000

# terminal 2 — the resource server
pip install -r requirements.txt
python server.py                     # http://localhost:9001

# terminal 3 — get a token, then point an MCP client at :9001/mcp
cd ../cimd-demo/auth-server && python get-token.py

Der Ablauf

1. Der Client ruft /mcp ohne Token auf und erhält 401 mit WWW-Authenticate: Bearer ..., resource_metadata="…".

2. Der Client folgt dieser Angabe zu /.well-known/oauth-protected-resource/mcp und erfährt, welcher Autorisierungsserver gültige Tokens ausstellt.

3. Der Client authentifiziert sich direkt bei Keycloak, wobei er seine Metadaten-Dokument-URL als client_id verwendet. Keycloak ruft diese URL ab und materialisiert den Client.

4. Der Client ruft /mcp erneut mit dem Bearer-Token auf.

RFC 9728 §3.1 platziert das Well-Known-Segment zwischen Host und Ressourcenpfad, daher befindet sich das Discovery-Dokument unter /.well-known/oauth-protected-resource/mcp. Der bloße Pfad ist eine 404.

Werkzeuge

• whoami() — sub, preferred_username, azp, scope, exp, iss aus dem Token des Aufrufers, plus registered_via_cimd. Liest nur das Token; kein Keycloak-Aufruf, funktioniert also auch dann, wenn die Admin-Zugangsdaten falsch sind.

• list_clients(only_cimd=False) — Realm-Clients, URL-förmige client_ids nach oben sortiert, sodass der aufrufende Client in der ersten Zeile landet.

• get_client_metadata(client_id) — Keycloaks eigene Darstellung eines Clients. Dies ist Keycloaks abgeleitete Ansicht, nicht das veröffentlichte Dokument.

CIMD wird erkannt, wenn client_id mit http:// oder https:// beginnt. Eine URL-förmige client_id ist das Erkennungsmerkmal.

get_client_metadata entfernt secret und registrationAccessToken vor der Rückgabe. Beide sind aktive Bearer-Zugangsdaten, und diese Ausgabe landet auf einem Projektor und in einer Aufzeichnung.

Zwei bekannte Lücken

RFC-8707-Ressourcenindikatoren. audience= ist vorhanden, aber im JWTVerifier auskommentiert. Eine Audience-Einschränkung des Tokens würde erfordern, dass der Client resource bei /authorize sendet, und Keycloak 26.7s CIMD-Pfad berücksichtigt dies noch nicht (keycloak#45106, keycloak#45284). Das Token trägt also Keycloaks übliche account-Audience, und dieser Server kann die Audience nicht einschränken. Absichtlich sichtbar.

Keine Scope-Durchsetzung. required_scopes ist nicht gesetzt, daher wird jedes signaturgültige, nicht abgelaufene Token aus dem Realm akzeptiert — einschließlich eines aus einem admin-cli-Password-Grant. Das ist auf der Bühne nützlich: whoami() mit einem Admin-Token ausführen (azp ist ein opaker String) und erneut mit dem CIMD-Token (azp ist eine URL), dasselbe Werkzeug, derselbe Server, der Unterschied in einem Feld. Es bedeutet auch, dass man sicher sein muss, welches Token man in der Hand hält.

Konfiguration

Alles per os.getenv mit localhost-Standardwerten.

KEYCLOAK_ISSUER und KEYCLOAK_JWKS_URI sind separat konfigurierbar und nicht voneinander abgeleitet: In Kubernetes ist der Issuer die öffentliche URL, sodass iss dem entspricht, was Clients sehen, während der JWKS-Abruf an den Service im Cluster gehen sollte.

fastmcp ist exakt gepinnt. Die Auth-Schnittstelle ändert sich — resource_server_url wurde zu base_url, AccessToken.claims kam in 2.11.3 hinzu — und allowed_client_redirect_uris ist in keiner Version ein Parameter von RemoteAuthProvider, egal, was die Doku zeigt. Es gehört zu OAuthProxy, den dieser Server nicht verwendet.