iamops.dev
Argo auf X RSS-Feed
DEDeutsch

Labs Technisch 4 Min. Lesezeit

Einen MCP-Server mit OAuth schützen: Token-Passthrough ablehnen und pro nachgelagerter API tauschen

Labor mit dem offiziellen MCP-Python-SDK und Keycloak: 401-Handshake, Audience-Prüfung, RFC-8693-Tausch für die Zahlungs-API und ein abgelehntes Passthrough.

Zwei Terminalaufnahmen aus meinem Lab: eine MCP-Anfrage ohne Token, mit 401 abgelehnt, und eine Introspection, die ein Token für die Payments-API als aktiv und für den MCP-Server als inaktiv zeigt.
Kurz gesagtEin MCP-Server ist ein OAuth-Resource-Server: Er antwortet mit 401 und…
  • Ein MCP-Server ist ein OAuth-Resource-Server: Er antwortet mit 401 und Protected Resource Metadata, damit Clients den Authorization Server finden.
  • Er prüft jedes Bearer Token per Introspektion und lehnt eines ab, dessen Audience den MCP-Server selbst nicht enthält.
  • Für eine nachgelagerte API tauscht er das Token (RFC 8693), statt das Token des Aufrufers weiterzureichen.
  • Ein absichtliches Passthrough scheitert: Das getauschte Token für die Zahlungs-API ist für den MCP-Server inaktiv und liefert 401.
  • Protokolliere Nutzer, Agent-Client und nachgelagerte Audience in einer Zeile, damit Audits die Kette nachvollziehen können.
Dieses Lab nachbauen 6 Schritte

Dieses Lab habe ich so geschrieben, dass Sie es selbst nachbauen können. Jeder Schritt enthält die Befehle zum Kopieren und die Ausgabe, die ich bekommen habe, und Sie können ihn als erledigt abhaken. Die Haken bleiben nur in diesem Browser.

Zu den Schritten

So funktioniert es

Kopiert einen fertigen Prompt für Claude Code, Cursor, Codex oder einen anderen Coding-Agenten. Nur für Testumgebungen.

Prompt anzeigen
I want to run a hands-on lab from iamops.dev, and I would like your help to do it safely.

Lab: Einen MCP-Server mit OAuth schützen: Token-Passthrough ablehnen und pro nachgelagerter API tauschen
Read the whole lab here (Markdown): https://iamops.dev/de/mcp-server-no-token-passthrough.md

What the lab needs before the first step:
- The Keycloak lab is running with its realm, three clients and user alice
- Python 3.12 or newer, curl and jq
- Values I have to set myself (the lab uses placeholders): <ALICE_PASSWORD>, <AGENT_CLIENT_SECRET>, <MCP_SERVER_CLIENT_SECRET>, <PAYMENTS_API_CLIENT_SECRET>

How I want you to work:
1. Read the lab from start to finish first (each step lists its own prerequisites). Then check that the prerequisites are in place and that the tool versions match what the lab expects. Tell me what is missing before you run anything.
2. Run one step at a time. Before each command, show it to me and say in a sentence what it does.
3. Ask me before anything that costs money, creates cloud resources, touches a real tenant or account, or deletes anything. Wait for my answer.
4. Use the placeholders from the lab. Never paste real secrets, tokens or production identities into a command, a file or this chat. If a value is needed, tell me where to set it myself.
5. After each step, compare the output with the expected output in the lab. If it does not match, stop and tell me what differs. Do not carry on or invent a fix without asking me.
6. At the end, report what passed, what failed and which cleanup you did. Then offer to tick the steps off for me. The lab page keeps ticks only in my browser, so if you cannot do that, list the steps I should tick.

This lab is for test environments only. Do not run it against production, or against a tenant or account that holds real data or real users.

You may answer in my language.

Am 10. November 2026 hat WorkOS Token Exchange (RFC 8693) zu WorkOS Connect hinzugefügt, damit ein MCP-Server nachgelagerte APIs für einen Nutzer aufrufen kann, ohne dessen Token durchzureichen. Genau dieses Muster erwartet die MCP-Autorisierungsspezifikation. Ich habe es von Hand mit dem offiziellen Python-SDK nachgebaut, damit jede Regel sichtbar wird.

Es baut auf dem Keycloak-Token-Exchange-Labor auf: gleicher Realm, gleiche drei Clients.

Was das Labor zeigt#

Ein mit dem offiziellen Python-SDK (mcp 2.3.0) geschriebener MCP-Server arbeitet als OAuth-Resource-Server für einen Keycloak-Realm. Er tut vier Dinge:

  1. Er beantwortet eine Anfrage ohne Token mit 401 und einem Verweis auf seine Protected Resource Metadata (RFC 9728), sodass ein Client den Autorisierungsserver finden kann, ohne ihn fest einzutragen.
  2. Er prüft jedes Bearer-Token per Introspektion bei Keycloak und lehnt Tokens ab, deren Audience den MCP-Server selbst nicht enthält.
  3. Für ein Tool tauscht er das Token des Aufrufers gegen ein Token für die Zahlungs-API (RFC 8693), statt es weiterzureichen.
  4. Er lehnt ein für die Zahlungs-API ausgestelltes Token ab, wenn jemand es dem MCP-Server vorlegt (ein Passthrough-Versuch).

Der Verifier ist kurz. Die entscheidende Zeile ist die Audience-Prüfung:

python
data = introspect(token)            # RFC 7662, as the mcp-server client
aud = data.get("aud", [])
aud = [aud] if isinstance(aud, str) else aud
if not data.get("active") or "mcp-server" not in aud:
    return None                     # inactive, or minted for another API: no passthrough

Der Ablauf#

Legen Sie die SDK-Version fest: mcp 2.x hat FastMCP in MCPServer umbenannt, und SDKs ändern ihre Auth-Klassen zwischen Versionen. Der Server lauscht auf 127.0.0.1:8001.

Ohne Token. Die erste Anfrage ist der Discovery-Handshake, mit dem jeder MCP-Client beginnt: ein 401, dessen WWW-Authenticate-Header eine resource_metadata-URL enthält, und ein Metadatendokument, das den Realm als Autorisierungsserver nennt.

Terminalausgabe: Eine Anfrage ohne Token liefert 401 Unauthorized mit einem www-authenticate-Header, der auf die Metadaten der geschützten Ressource verweist; das Metadatendokument nennt den Keycloak-Realm als Autorisierungsserver.
Der 401-Handshake. Der Client erfährt aus dem Metadatendokument, wo er ein Token bekommt, nicht aus einer Konfiguration.

Mit Token. Ein kleines Skript holt ein Nutzer-Token für den Client agent, öffnet eine MCP-Sitzung und ruft beide Tools auf. whoami zeigt, dass der Server den Nutzer über den Agent-Client sieht; downstream_token zeigt, wie der Server das Token gegen eines tauscht, das auf die Zahlungs-API begrenzt ist.

Terminalausgabe der beiden Tool-Aufrufe: whoami liefert Subject, Agent-Client und Scopes; downstream_token liefert ein Token mit Audience payments-api und autorisierter Partei mcp-server. Das Subject ist durch einen Platzhalter ersetzt.
Zwei Tools. Das erste zeigt, wer aufgerufen hat. Das zweite zeigt das getauschte Token: Audience payments-api, autorisierte Partei mcp-server, gleiches Subject. Das Subject ist ein Platzhalter.

Derselbe Aufruf funktioniert über den MCP-Inspector-Kommandozeilenclient, den Standardweg, um nachzustellen, was ein MCP-Host tun würde. Legen Sie seine Version in Skripten fest; dieses Labor nutzte 2.15.0.

Der Passthrough-Versuch. Erzeugen Sie ein frisches getauschtes Token, betrachten Sie es per Introspektion von beiden Seiten und legen Sie es dem MCP-Server vor.

Terminalausgabe: Die Introspektion meldet das Token als aktiv für den Client payments-api und als inaktiv für den Client mcp-server; die Vorlage beim MCP-Server liefert 401.
Kein Passthrough. Keycloak meldet das Token nur dem Client als aktiv, für den es ausgestellt wurde. Der MCP-Server antwortet mit 401. Client Secrets sind Platzhalter.

Stolperfallen#

  • Introspektion oder lokale Validierung? Das Labor nutzt Introspektion: sofortiger Widerruf, dafür ein Roundtrip zum Autorisierungsserver. Die Alternative ist lokale JWT-Validierung gegen die JWKS; notieren Sie, was Sie verlieren und gewinnen.
  • Prüfen Sie die Audience, nicht nur die Signatur. Ein gültiges Token für eine andere API bleibt das falsche Token. Die Audience-Prüfung macht aus dem Passthrough ein 401.
  • Tokens leben in diesem Aufbau fünf Minuten; erzeugen Sie das Passthrough-Token also direkt vor dem Test.
  • SDK-Drift. Klassennamen und Auth-Hooks haben sich zwischen Hauptversionen verschoben; testen Sie mit der Version, die Sie ausliefern.

Sicherheitserkenntnisse#

  1. Ein MCP-Server ist ein OAuth-Resource-Server. Er veröffentlicht Metadaten, validiert die Audience und lehnt alles ab, was nicht für ihn bestimmt ist.
  2. Reichen Sie das Token des Aufrufers nie an eine nachgelagerte API weiter. Tauschen Sie es pro nachgelagerter Audience, enger gefasst und kurzlebig.
  3. Lassen Sie den Autorisierungsserver entscheiden, wer ein Token als aktiv sieht. Ein Token, das nur beim vorgesehenen Empfänger funktioniert, begrenzt, was ein kompromittierter Zwischenschritt anrichten kann.
  4. Protokollieren Sie eine Zeile, die Nutzer, Agent-Client und nachgelagerte Audience verbindet; das Token allein erzählt einem Auditor nicht die ganze Geschichte.

Was nicht ausgeführt wurde#

Der OAuth-Ablauf der MCP-Inspector-Weboberfläche wurde nicht ausgeführt (der Client agent des Labors erlaubt dafür eine localhost-Weiterleitung). Dynamische Client-Registrierung wurde nicht verwendet; der Client ist vorregistriert. Alles lief auf einem Rechner mit Wegwerfkonten. Für dieses Labor wird keine Aufzeichnung veröffentlicht.

Die Terminalbilder wurden aus der gespeicherten Ausgabe des Laufs erzeugt; Kennungen, Geheimnisse und Zeitstempel sind durch Platzhalter ersetzt.

Dieses Lab nachbauen#

Dieses Lab läuft in etwa 30 Minuten auf einem Laptop. Sie brauchen den Keycloak-Realm aus dem Token-Exchange-Lab, einen kleinen MCP-Server in Python und ein paar curl-Aufrufe. Öffnen Sie jeden Schritt, kopieren Sie die Blöcke und vergleichen Sie die Ausgabe mit meiner.

Jeder Wert in spitzen Klammern ist ein Platzhalter für Ihre Testumgebung. Nichts auf dieser Seite ist eine echte Kennung oder ein echtes Geheimnis.

Variablen einmal setzen

bash · env.sh
# Paste into every terminal you use for this lab. Same values as in the Keycloak lab.
export KC_URL="http://localhost:8080"
export KC_REALM="agentlab"
export ALICE_PASSWORD='<ALICE_PASSWORD>'
export AGENT_SECRET='<AGENT_CLIENT_SECRET>'
export MCP_SECRET='<MCP_SERVER_CLIENT_SECRET>'
export PAYMENTS_SECRET='<PAYMENTS_API_CLIENT_SECRET>'
export TOKEN_URL="$KC_URL/realms/$KC_REALM/protocol/openid-connect/token"
export INTROSPECT_URL="$TOKEN_URL/introspect"
export MCP_URL="http://127.0.0.1:8001/mcp"
Schritt 1SDK installieren und Realm prüfen

Ziel. Installieren Sie das MCP-Python-SDK in einer sauberen virtualenv und prüfen Sie, ob der Keycloak-Realm aus dem ersten Lab noch läuft.

Voraussetzungen

  • Das Keycloak-Lab läuft mit Realm, drei Clients und dem Benutzer alice
  • Python 3.12 oder neuer, curl und jq
bash · install.sh
python3 -m venv .venv && . .venv/bin/activate
pip install "mcp==2.3.0" httpx
# the realm answers
curl -s -o /dev/null -w "%{http_code}\n" "$KC_URL/realms/$KC_REALM/.well-known/openid-configuration"

Erwartete Ausgabe

Ausgabe
Successfully installed ... httpx-... mcp-2.3.0 ...
200
Schritt 2MCP-Server schreiben und starten

Ziel. Starten Sie einen MCP-Server, der jedes Token per Introspektion prüft und alle ablehnt, die nicht für ihn bestimmt sind.

Voraussetzungen

  • Die virtualenv aus dem vorigen Schritt ist aktiv
  • Die Variablen aus env.sh sind in diesem Terminal gesetzt, und Port 8001 ist frei
python · payments_mcp.py
"""An MCP server that is an OAuth resource server for Keycloak, and calls a downstream API
for the user with RFC 8693 token exchange. Tested with mcp 2.3.0 and Keycloak 26.8.2. Lab use only."""
import base64
import json
import os

import httpx
from mcp.server.auth.middleware.auth_context import get_access_token
from mcp.server.auth.provider import AccessToken
from mcp.server.auth.settings import AuthSettings
from mcp.server.mcpserver import MCPServer

KC = f"{os.environ['KC_URL']}/realms/{os.environ['KC_REALM']}"
CLIENT_ID = "mcp-server"
CLIENT_SECRET = os.environ["MCP_SECRET"]
RESOURCE = "http://localhost:8001/mcp"


class IntrospectionVerifier:
    """RFC 7662 introspection at Keycloak, then an audience check."""

    async def verify_token(self, token: str) -> AccessToken | None:
        async with httpx.AsyncClient() as http:
            r = await http.post(f"{KC}/protocol/openid-connect/token/introspect",
                                data={"token": token}, auth=(CLIENT_ID, CLIENT_SECRET))
        data = r.json()
        aud = data.get("aud", [])
        aud = [aud] if isinstance(aud, str) else aud
        if not data.get("active") or CLIENT_ID not in aud:
            return None  # inactive, or minted for another API: no token passthrough
        return AccessToken(token=token, client_id=data.get("azp", ""),
                           scopes=data.get("scope", "").split(), expires_at=data.get("exp"),
                           subject=data.get("sub"), claims={"iss": data.get("iss")})


mcp = MCPServer(
    "payments-lab",
    token_verifier=IntrospectionVerifier(),
    auth=AuthSettings(issuer_url=KC, resource_server_url=RESOURCE, validate_token_resource=False),
)


def claims(jwt: str) -> dict:
    part = jwt.split(".")[1]
    return json.loads(base64.urlsafe_b64decode(part + "=" * (-len(part) % 4)))


@mcp.tool()
async def whoami() -> dict:
    """Who called this MCP server, according to the bearer token."""
    t = get_access_token()
    return {"subject": t.subject, "client": t.client_id, "scopes": t.scopes}


@mcp.tool()
async def downstream_token() -> dict:
    """Exchange the caller's token for a payments-api token (RFC 8693) and show its claims."""
    t = get_access_token()
    async with httpx.AsyncClient() as http:
        r = await http.post(f"{KC}/protocol/openid-connect/token", auth=(CLIENT_ID, CLIENT_SECRET), data={
            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
            "subject_token": t.token,
            "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
            "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
            "audience": "payments-api",
            "scope": "aud-payments-api",
        })
    body = r.json()
    if "access_token" not in body:
        return {"error": body}
    c = claims(body["access_token"])
    return {k: c.get(k) for k in ("aud", "azp", "sub", "scope", "exp")}


if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8001)
bash · run-server.sh
python payments_mcp.py   # keep this terminal open

Erwartete Ausgabe

Ausgabe
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
Schritt 3Den Server ohne Token aufrufen

Ziel. Sehen Sie sich den Discovery-Handshake an: ein 401, das auf die Protected Resource Metadata zeigt, und ein Metadatendokument, das den Realm nennt.

Voraussetzungen

  • Der Server aus dem vorigen Schritt läuft
  • Nutzen Sie ein zweites Terminal mit geladenem env.sh
bash · no-token.sh
curl -si -X POST "$MCP_URL" -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' -d '{}' | grep -iE '^HTTP|www-authenticate'
curl -s http://127.0.0.1:8001/.well-known/oauth-protected-resource/mcp | jq .

Erwartete Ausgabe

Ausgabe
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer error="invalid_token", error_description="Authentication required", resource_metadata="http://localhost:8001/.well-known/oauth-protected-resource/mcp"
{
  "resource": "http://localhost:8001/mcp",
  "authorization_servers": [
    "http://localhost:8080/realms/agentlab"
  ],
  "bearer_methods_supported": [
    "header"
  ]
}
Schritt 4Beide Tools mit einem Benutzer-Token aufrufen

Ziel. Holen Sie ein Token für den Client agent, öffnen Sie eine MCP-Sitzung und rufen Sie whoami und downstream_token auf.

Voraussetzungen

  • Der Server läuft noch im ersten Terminal
  • jq ist installiert; das Skript nutzt den Password Grant, nur für Labs
bash · call.sh
#!/usr/bin/env bash
# Get a user token for the agent client, open an MCP session and call both tools with curl.
set -euo pipefail
TOKEN=$(curl -s -d grant_type=password -d client_id=agent -d client_secret="$AGENT_SECRET" \
  -d username=alice -d password="$ALICE_PASSWORD" -d scope=openid "$TOKEN_URL" | jq -r .access_token)
H=(-H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream')
SID=$(curl -s -D - -o /dev/null "${H[@]}" "$MCP_URL" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
  | awk -F': ' 'tolower($1)=="mcp-session-id"{print $2}' | tr -d '\r')
curl -s "${H[@]}" -H "mcp-session-id: $SID" -H 'mcp-protocol-version: 2025-06-18' "$MCP_URL" -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null
for TOOL in whoami downstream_token; do
  echo "--- $TOOL"
  curl -s "${H[@]}" -H "mcp-session-id: $SID" -H 'mcp-protocol-version: 2025-06-18' "$MCP_URL" \
    -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"$TOOL\",\"arguments\":{}}}" | sed -n 's/^data: //p' | jq -r '.result.content[0].text'
done
bash · run-call.sh
chmod +x call.sh && ./call.sh

Erwartete Ausgabe

Ausgabe
--- whoami
{
  "subject": "<user-id>",
  "client": "agent",
  "scopes": [
    "openid",
    "profile",
    "aud-mcp-server",
    "email"
  ]
}
--- downstream_token
{
  "aud": "payments-api",
  "azp": "mcp-server",
  "sub": "<user-id>",
  "scope": "aud-payments-api profile email",
  "exp": <timestamp>
}
Schritt 5Absichtlich ein Passthrough versuchen

Ziel. Nehmen Sie das Token, das für die Zahlungs-API ausgestellt wurde, und zeigen Sie es dem MCP-Server. Es muss abgelehnt werden.

Voraussetzungen

  • Ein frisch getauschtes Token: es lebt 5 Minuten, also führe das gleich aus
bash · passthrough.sh
# 1. a user token for the agent, then the exchange as the MCP server (same calls as in the Keycloak lab)
USER_AT=$(curl -s -d grant_type=password -d client_id=agent -d client_secret="$AGENT_SECRET" \
  -d username=alice -d password="$ALICE_PASSWORD" -d scope=openid "$TOKEN_URL" | jq -r .access_token)
T=$(curl -s -u "mcp-server:$MCP_SECRET" -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token="$USER_AT" -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d requested_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d audience=payments-api -d scope=aud-payments-api "$TOKEN_URL" | jq -r .access_token)
# 2. who may see that token as active?
curl -s -u "payments-api:$PAYMENTS_SECRET" -d token="$T" "$INTROSPECT_URL" | jq -c '{caller:"payments-api",active,aud,azp}'
curl -s -u "mcp-server:$MCP_SECRET" -d token="$T" "$INTROSPECT_URL" | jq -c '{caller:"mcp-server",active,aud,azp}'
# 3. present it to the MCP server
curl -s -o /dev/null -w "%{http_code}\n" "$MCP_URL" -H "authorization: Bearer $T" \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d '{}'

Erwartete Ausgabe

Ausgabe
{"caller":"payments-api","active":true,"aud":["payments-api","account"],"azp":"mcp-server"}
{"caller":"mcp-server","active":false,"aud":null,"azp":null}
401
Schritt 6Aufräumen

Ziel. Stoppen Sie den Server, löschen Sie die virtualenv und das Skript und entfernen Sie die Secrets aus der Shell.

Voraussetzungen

  • Keycloak räumen Sie im Keycloak-Lab auf, im Schritt Aufräumen
bash · cleanup.sh
pkill -f payments_mcp.py || true
deactivate 2>/dev/null || true
rm -rf .venv payments_mcp.py call.sh
unset ALICE_PASSWORD AGENT_SECRET MCP_SECRET PAYMENTS_SECRET USER_AT T
# check: nothing listens on port 8001 any more
curl -s -o /dev/null -w "%{http_code}\n" "$MCP_URL"

Erwartete Ausgabe

Ausgabe
000

Quellen#

Diesen Beitrag diskutieren#

Hat es dir geholfen? Teile es und sag mir, was du denkst.

Auf X folgen

Neue Beiträge per E-Mail

Eine E-Mail pro Woche mit neuen Beiträgen und Labs. Jederzeit abbestellbar.

Ihre Adresse wird bei Kit gespeichert, dem Dienst, der die E-Mails versendet. Details

Verwandte Beiträge und Labs