Zum Hauptinhalt springen

Tutorial: Wer bin ich? (Tutorial: Who am I?)

Dieses Tutorial führt dich durch den Prozess der Einrichtung von MCP Auth, um Benutzer zu authentifizieren und deren Identitätsinformationen vom Autorisierungsserver abzurufen.

Nach Abschluss dieses Tutorials hast du:

  • ✅ Ein grundlegendes Verständnis davon, wie du MCP Auth zur Authentifizierung von Benutzern verwendest.
  • ✅ Einen MCP-Server, der ein Tool zum Abrufen von Benutzeridentitätsinformationen bereitstellt.

Überblick​

Das Tutorial umfasst die folgenden Komponenten:

  • MCP-Server: Ein einfacher MCP-Server, der die offiziellen MCP SDKs verwendet, um Anfragen zu verarbeiten.
  • MCP Inspector: Ein visuelles Testwerkzeug für MCP-Server. Es fungiert auch als OAuth / OIDC-Client, um den Autorisierungsfluss zu starten und Zugangstokens abzurufen.
  • Autorisierungsserver: Ein OAuth 2.1- oder OpenID Connect-Anbieter, der Benutzeridentitäten verwaltet und Zugangstokens ausstellt.

Hier ist ein Überblicksdiagramm der Interaktion zwischen diesen Komponenten:

Deinen Autorisierungsserver verstehen​

Benutzeridentitätsinformationen abrufen​

Um dieses Tutorial abzuschließen, sollte dein Autorisierungsserver eine API zum Abrufen von Benutzeridentitätsinformationen bereitstellen:

Logto ist ein OpenID Connect-Anbieter, der den Standard-userinfo-Endpunkt unterstützt, um Benutzeridentitätsinformationen abzurufen.

Um ein Zugangstoken zu erhalten, das für den Zugriff auf den userinfo-Endpunkt verwendet werden kann, sind mindestens zwei Berechtigungen (scopes) erforderlich: openid und profile. Du kannst weiterlesen, da wir die Berechtigungskonfiguration später behandeln.

Dynamische Client-Registrierung​

Die dynamische Client-Registrierung ist für dieses Tutorial nicht erforderlich, kann aber nützlich sein, wenn du den MCP-Client-Registrierungsprozess mit deinem Autorisierungsserver automatisieren möchtest. Siehe Ist Dynamic Client Registration erforderlich? für weitere Details.

MCP-Server einrichten​

Wir verwenden die offiziellen MCP SDKs, um einen MCP-Server mit einem whoami-Tool zu erstellen, das Benutzeridentitätsinformationen vom Autorisierungsserver abruft.

Ein neues Projekt erstellen​

mkdir mcp-server
cd mcp-server
uv init # Oder verwende `pipenv` oder `poetry`, um eine neue virtuelle Umgebung zu erstellen

MCP SDK und Abhängigkeiten installieren​

pip install "mcp[cli]" starlette uvicorn

Oder ein anderes Paketverwaltungstool deiner Wahl, wie uv oder poetry.

MCP-Server erstellen​

Erstellen wir zunächst einen MCP-Server, der ein whoami-Tool implementiert.

Erstelle eine Datei namens whoami.py und füge folgenden Code hinzu:

from mcp.server.fastmcp import FastMCP
from starlette.applications import Starlette
from starlette.routing import Mount
from typing import Any

mcp = FastMCP("WhoAmI")

@mcp.tool()
def whoami() -> dict[str, Any]:
    """Ein Tool, das die Informationen des aktuellen Benutzers zurückgibt."""
    return {"error": "Nicht authentifiziert"}

app = Starlette(
    routes=[Mount('/', app=mcp.sse_app())]
)

Starte den Server mit:

uvicorn whoami:app --host 0.0.0.0 --port 3001

MCP-Server inspizieren​

MCP Inspector klonen und ausführen​

Jetzt, da der MCP-Server läuft, können wir den MCP Inspector verwenden, um zu sehen, ob das whoami-Tool verfügbar ist.

Aufgrund der aktuellen Implementierung haben wir den MCP Inspector geforkt, um ihn flexibler und skalierbarer für Authentifizierung und Autorisierung zu machen. Wir haben auch einen Pull Request an das Original-Repository eingereicht, um unsere Änderungen einzubringen.

Um den MCP Inspector auszuführen, kannst du folgenden Befehl verwenden (Node.js wird benötigt):

git clone https://github.com/mcp-auth/inspector.git
cd inspector
npm install
npm run dev

Öffne dann deinen Browser und navigiere zu http://localhost:6274/ (oder einer anderen im Terminal angezeigten URL), um auf den MCP Inspector zuzugreifen.

MCP Inspector mit dem MCP-Server verbinden​

Bevor wir fortfahren, überprüfe folgende Konfiguration im MCP Inspector:

  • Transporttyp: Auf SSE setzen.
  • URL: Auf die URL deines MCP-Servers setzen. In unserem Fall sollte das http://localhost:3001/sse sein.

Jetzt kannst du auf die Schaltfläche "Connect" klicken, um zu sehen, ob der MCP Inspector eine Verbindung zum MCP-Server herstellen kann. Wenn alles in Ordnung ist, solltest du den Status "Connected" im MCP Inspector sehen.

Checkpoint: Das whoami-Tool ausführen​

  1. Klicke im oberen Menü des MCP Inspectors auf den Tab "Tools".
  2. Klicke auf die Schaltfläche "List Tools".
  3. Du solltest das whoami-Tool auf der Seite sehen. Klicke darauf, um die Tool-Details zu öffnen.
  4. Du solltest auf der rechten Seite die Schaltfläche "Run Tool" sehen. Klicke darauf, um das Tool auszuführen.
  5. Du solltest das Tool-Ergebnis mit der JSON-Antwort {"error": "Nicht authentifiziert"} sehen.

MCP Inspector erster Lauf

Integration mit deinem Autorisierungsserver​

Um diesen Abschnitt abzuschließen, sind mehrere Überlegungen zu beachten:

Die Issuer-URL deines Autorisierungsservers

Dies ist normalerweise die Basis-URL deines Autorisierungsservers, z. B. https://auth.example.com. Einige Anbieter haben einen Pfad wie https://example.logto.app/oidc, daher solltest du die Dokumentation deines Anbieters prüfen.

Wie du die Metadaten des Autorisierungsservers abrufst
  • Wenn dein Autorisierungsserver dem OAuth 2.0 Authorization Server Metadata oder OpenID Connect Discovery entspricht, kannst du die integrierten MCP Auth-Utilities verwenden, um die Metadaten automatisch abzurufen.
  • Wenn dein Autorisierungsserver diese Standards nicht unterstützt, musst du die Metadaten-URL oder Endpunkte manuell in der MCP-Server-Konfiguration angeben. Prüfe die Dokumentation deines Anbieters für die spezifischen Endpunkte.
Wie du den MCP Inspector als Client in deinem Autorisierungsserver registrierst
  • Wenn dein Autorisierungsserver Dynamic Client Registration unterstützt, kannst du diesen Schritt überspringen, da sich der MCP Inspector automatisch als Client registriert.
  • Wenn dein Autorisierungsserver keine Dynamic Client Registration unterstützt, musst du den MCP Inspector manuell als Client in deinem Autorisierungsserver registrieren.
Wie du Benutzeridentitätsinformationen abrufst und wie du die Parameter der Autorisierungsanfrage konfigurierst

  • Für OpenID Connect-Anbieter: In der Regel musst du beim Starten des Autorisierungsflusses mindestens die Berechtigungen openid und profile anfordern. Dadurch wird sichergestellt, dass das vom Autorisierungsserver zurückgegebene Zugangstoken die erforderlichen Berechtigungen für den Zugriff auf den userinfo-Endpunkt enthält, um Benutzeridentitätsinformationen abzurufen.

    Hinweis: Einige Anbieter unterstützen den userinfo-Endpunkt möglicherweise nicht.

  • Für OAuth 2.0 / OAuth 2.1-Anbieter: Prüfe die Dokumentation deines Anbieters, um zu erfahren, wie du mit einem Zugangstoken Benutzeridentitätsinformationen abrufen kannst und welche Parameter erforderlich sind, um ein solches Zugangstoken beim Starten des Autorisierungsflusses zu erhalten.

Während jeder Anbieter eigene spezifische Anforderungen haben kann, führen dich die folgenden Schritte durch den Prozess der Integration des MCP Inspectors und MCP Servers mit anbieter-spezifischen Konfigurationen.

MCP Inspector als Client registrieren​

Die Integration mit Logto ist unkompliziert, da es sich um einen OpenID Connect-Anbieter handelt, der den Standard-userinfo-Endpunkt unterstützt, um Benutzeridentitätsinformationen abzurufen.

Da Logto derzeit keine Dynamic Client Registration unterstützt, musst du den MCP Inspector manuell als Client in deinem Logto-Tenant registrieren:

  1. Öffne deinen MCP Inspector, klicke auf die Schaltfläche "OAuth Configuration". Kopiere den Redirect URL (auto-populated)-Wert, der etwa so aussehen sollte: http://localhost:6274/oauth/callback.
  2. Melde dich bei der Logto Console (oder deiner selbst gehosteten Logto Console) an.
  3. Navigiere zum Tab "Applications", klicke auf "Create application". Klicke unten auf der Seite auf "Create app without framework".
  4. Fülle die Anwendungsdetails aus und klicke dann auf "Create application":
    • Wähle einen Anwendungstyp: Wähle "Single-page application".
    • Anwendungsname: Gib einen Namen für deine Anwendung ein, z. B. "MCP Inspector".
  5. Im Bereich "Settings / Redirect URIs" füge den zuvor kopierten Redirect URL (auto-populated)-Wert ein. Klicke dann unten auf "Save changes".
  6. Im oberen Bereich siehst du den Wert "App ID". Kopiere ihn.
  7. Gehe zurück zum MCP Inspector und füge den "App ID"-Wert im Bereich "OAuth Configuration" unter "Client ID" ein.
  8. Gib den Wert {"scope": "openid profile email"} im Feld "Auth Params" ein. Dadurch wird sichergestellt, dass das von Logto zurückgegebene Zugangstoken die erforderlichen Berechtigungen für den Zugriff auf den userinfo-Endpunkt enthält.

MCP Auth einrichten​

In deinem MCP-Server-Projekt musst du das MCP Auth SDK installieren und es so konfigurieren, dass es die Metadaten deines Autorisierungsservers verwendet.

Installiere zunächst das mcpauth-Paket:

pip install mcpauth

Oder ein anderes Paketverwaltungstool deiner Wahl, wie uv oder poetry.

MCP Auth benötigt die Metadaten des Autorisierungsservers, um initialisiert werden zu können. Je nach Anbieter:

Die Issuer-URL findest du auf der Anwendungsdetailseite in der Logto Console im Abschnitt "Endpoints & Credentials / Issuer endpoint". Sie sollte etwa so aussehen: https://my-project.logto.app/oidc.

Aktualisiere die whoami.py, um die MCP Auth-Konfiguration einzubinden:

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

auth_issuer = '<issuer-endpoint>'  # Ersetze dies durch deinen Issuer-Endpunkt
auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC)
mcp_auth = MCPAuth(server=auth_server_config)

Nun müssen wir einen benutzerdefinierten Zugangstoken (Access token) Verifizierer erstellen, der die Benutzeridentitätsinformationen vom Autorisierungsserver mit dem vom MCP-Inspector bereitgestellten Zugangstoken abruft.

import pydantic
import requests
from mcpauth.exceptions import (
    MCPAuthTokenVerificationException,
    MCPAuthTokenVerificationExceptionCode,
)
from mcpauth.types import AuthInfo

def verify_access_token(token: str) -> AuthInfo:
    """
    Überprüft das bereitgestellte Bearer-Token, indem Benutzerinformationen vom Autorisierungsserver abgerufen werden.
    Wenn das Token gültig ist, wird ein `AuthInfo`-Objekt mit den Benutzerinformationen zurückgegeben.

    :param token: Das vom MCP-Inspector erhaltene Bearer-Token.
    """

    issuer = auth_server_config.metadata.issuer
    endpoint = auth_server_config.metadata.userinfo_endpoint # Der Anbieter sollte den userinfo-Endpunkt unterstützen
    if not endpoint:
        raise ValueError(
            "Userinfo-Endpunkt ist in den Auth-Server-Metadaten nicht konfiguriert."
        )

    try:
        response = requests.get(
            endpoint,
            headers={"Authorization": f"Bearer {token}"}, # Standard Bearer-Token-Header
        )
        response.raise_for_status() # Fehler bei HTTP-Fehlern auslösen
        json = response.json() # Die JSON-Antwort parsen
        return AuthInfo(
            token=token,
            subject=json.get("sub"), # 'sub' ist ein Standard-Anspruch (Claim) für das Subjekt (Benutzer-ID)
            issuer=issuer, # Verwende den Aussteller (Issuer) aus den Metadaten
            claims=json, # Alle Ansprüche (Claims) (JSON-Felder), die vom userinfo-Endpunkt zurückgegeben werden
        )
    # `AuthInfo` ist ein Pydantic-Modell, daher bedeuten Validierungsfehler meist, dass die Antwort nicht der erwarteten Struktur entspricht
    except pydantic.ValidationError as e:
        raise MCPAuthTokenVerificationException(
            MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN,
            cause=e,
        )
    # Andere Ausnahmen behandeln, die während der Anfrage auftreten können
    except Exception as e:
        raise MCPAuthTokenVerificationException(
            MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED,
            cause=e,
        )

MCP-Server aktualisieren​

Wir sind fast fertig! Jetzt ist es an der Zeit, den MCP-Server zu aktualisieren, um die MCP Auth-Route und Middleware-Funktion anzuwenden und das whoami-Tool so zu gestalten, dass es die tatsächlichen Benutzeridentitätsinformationen zurückgibt.

@mcp.tool()
def whoami() -> dict[str, Any]:
    """Ein Tool, das die Informationen des aktuellen Benutzers zurückgibt."""
    return (
        mcp_auth.auth_info.claims
        if mcp_auth.auth_info # Dies wird durch die Bearer-Auth-Middleware befüllt
        else {"error": "Nicht authentifiziert"}
    )

# ...

bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token))
app = Starlette(
    routes=[
        # Füge die Metadaten-Route hinzu (`/.well-known/oauth-authorization-server`)
        mcp_auth.metadata_route(),
        # Schütze den MCP-Server mit der Bearer-Auth-Middleware
        Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]),
    ],
)

Checkpoint: Das whoami-Tool mit Authentifizierung ausführen​

Starte deinen MCP-Server neu und öffne den MCP Inspector in deinem Browser. Wenn du auf die Schaltfläche "Connect" klickst, solltest du zur Anmeldeseite deines Autorisierungsservers weitergeleitet werden.

Sobald du dich angemeldet hast und zum MCP Inspector zurückkehrst, wiederhole die Schritte aus dem vorherigen Checkpoint, um das whoami-Tool auszuführen. Dieses Mal solltest du die vom Autorisierungsserver zurückgegebenen Benutzeridentitätsinformationen sehen.

MCP Inspector whoami Tool Ergebnis

info

Sieh dir das MCP Auth Python SDK Repository für den vollständigen Code des MCP-Servers (OIDC-Version) an.

Abschließende Hinweise​

🎊 Glückwunsch! Du hast das Tutorial erfolgreich abgeschlossen. Lass uns zusammenfassen, was wir gemacht haben:

  • Einen grundlegenden MCP-Server mit dem whoami-Tool eingerichtet
  • Den MCP-Server mit einem Autorisierungsserver unter Verwendung von MCP Auth integriert
  • Den MCP Inspector so konfiguriert, dass Benutzer authentifiziert und deren Identitätsinformationen abgerufen werden

Du möchtest vielleicht auch einige fortgeschrittene Themen erkunden, darunter:

Sieh dir unbedingt weitere Tutorials und die Dokumentation an, um das Beste aus MCP Auth herauszuholen.