Bearer-Authentifizierung im MCP-Server konfigurieren

Mit der neuesten MCP-Spezifikation agiert dein MCP-Server als Ressourcenserver, der Zugangstokens für geschützte Ressourcen validiert. MCP Auth bietet verschiedene Möglichkeiten, die Bearer-Autorisierung zu konfigurieren:

• JWT (JSON Web Token)-Modus: Eine integrierte Autorisierungsmethode, die JWTs mit Anspruchsüberprüfungen validiert.
• Benutzerdefinierter Modus: Ermöglicht es dir, deine eigene Autorisierungslogik zu implementieren.

Das Bearer-Auth-Middleware erfordert nun die Angabe, zu welcher Ressource der Endpunkt gehört, um eine korrekte Tokenvalidierung gegenüber den konfigurierten Autorisierungsservern zu ermöglichen.

Bearer-Authentifizierung mit JWT-Modus konfigurieren

Wenn dein OAuth / OIDC-Anbieter JWTs zur Autorisierung ausstellt, kannst du den integrierten JWT-Modus in MCP Auth verwenden. Er überprüft die JWT-Signatur, das Ablaufdatum und andere von dir angegebene Ansprüche; anschließend werden die Authentifizierungsinformationen im Request-Kontext für die weitere Verarbeitung in deiner MCP-Implementierung bereitgestellt.

Berechtigungsprüfung (Scope validation)

Hier ein Beispiel für die grundlegende Berechtigungsprüfung:

Python

from mcpauth import MCPAuth
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.routing import Mount
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyMCPServer")
mcp_auth = MCPAuth(
    # Initialisiere mit deiner Auth-Server-Konfiguration
)
bearer_auth = mcp_auth.bearer_auth_middleware("jwt", 
    resource="https://api.example.com",  # Gib an, zu welcher Ressource dieser Endpunkt gehört
    audience="https://api.example.com",  # Aktiviere die Zielgruppenvalidierung für Sicherheit
    required_scopes=["read", "write"] 
)

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

Node.js

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth = new MCPAuth({
  /* ... */
});
const bearerAuth = mcpAuth.bearerAuth('jwt', { 
  resource: 'https://api.example.com', // Gib an, zu welcher Ressource dieser Endpunkt gehört
  audience: 'https://api.example.com', // Aktiviere die Zielgruppenvalidierung für Sicherheit
  requiredScopes: ['read', 'write'] 
});

app.use('/mcp', bearerAuth, (req, res) => {
  // Jetzt enthält `req.auth` die Auth-Informationen
  console.log(req.auth);
});

Im obigen Beispiel haben wir angegeben, dass das JWT die Berechtigungen read und write benötigt. Wenn das JWT keine dieser Berechtigungen enthält, wird die Anfrage mit einem 403 Forbidden-Fehler abgelehnt.

Zielgruppenvalidierung (Audience validation, RFC 8707)

Für eine sichere Tokenvalidierung solltest du immer die Zielgruppenvalidierung aktivieren, indem du den Parameter audience angibst. Dadurch wird der aud (Zielgruppe)-Anspruch im JWT validiert, um sicherzustellen, dass das Token speziell für deine MCP-Server-Ressource ausgestellt wurde.

Audience Validation

Der Parameter audience ist gemäß der OAuth 2.0-Spezifikation für eine sichere Tokenvalidierung erforderlich. Er ist jedoch derzeit optional, um die Kompatibilität mit Autorisierungsservern zu gewährleisten, die noch keine Ressourcenindikatoren unterstützen. Aus Sicherheitsgründen bitte immer den Audience-Parameter angeben, wenn möglich. Zukünftige Versionen werden die Zielgruppenvalidierung verpflichtend machen, um die Spezifikation vollständig zu erfüllen.

Der Audience-Wert sollte in der Regel mit deinem Ressourcenindikator übereinstimmen:

Python

bearer_auth = mcp_auth.bearer_auth_middleware(
    "jwt",
    resource="https://api.example.com",  # Gib an, zu welcher Ressource dieser Endpunkt gehört
    audience="https://api.example.com",  # Aktiviere die Zielgruppenvalidierung für Sicherheit
    required_scopes=["read", "write"]
)

Node.js

const bearerAuth = mcpAuth.bearerAuth('jwt', {
  resource: 'https://api.example.com', // Gib an, zu welcher Ressource dieser Endpunkt gehört
  audience: 'https://api.example.com', // Aktiviere die Zielgruppenvalidierung für Sicherheit
  requiredScopes: ['read', 'write'],
});

Im obigen Beispiel validiert MCP Auth sowohl den aud-Anspruch im JWT als auch die erforderlichen Berechtigungen.

Benutzerdefinierte Optionen für die JWT-Überprüfung angeben

Du kannst auch benutzerdefinierte Optionen an die zugrunde liegende JWT-Überprüfungsbibliothek übergeben:

Python

Im Python SDK verwenden wir PyJWT für die JWT-Überprüfung. Du kannst folgende Optionen nutzen:

• leeway: Erlaubt eine gewisse Toleranz bei der Überprüfung der JWT-Ablaufzeit (in Sekunden). Standard ist 60 Sekunden.

bearer_auth = mcp_auth.bearer_auth_middleware(
    "jwt",
    resource="https://api.example.com",
    audience="https://api.example.com",
    required_scopes=["read", "write"],
    leeway=10,  # Reduziere Zeitabweichungen, indem du 10 Sekunden Toleranz erlaubst
)

Node.js

Im Node.js SDK verwenden wir die jose-Bibliothek für die JWT-Überprüfung. Du kannst folgende Optionen angeben:

• jwtVerify: Optionen für den JWT-Überprüfungsprozess (jwtVerify-Funktion von jose).
• remoteJwtSet: Optionen für das Abrufen des Remote-JWT-Sets (createRemoteJWKSet-Funktion von jose).

const bearerAuth = mcpAuth.bearerAuth('jwt', {
  resource: 'https://api.example.com',
  audience: 'https://api.example.com',
  requiredScopes: ['read', 'write'],
  jwtVerify: {
    clockTolerance: 60, // Erlaube eine Zeitabweichung von 60 Sekunden
  },
  remoteJwtSet: {
    timeoutDuration: 10 * 1000, // 10 Sekunden Timeout für das Abrufen des Remote-JWT-Sets
  },
});

Bearer-Authentifizierung mit benutzerdefinierter Überprüfung konfigurieren

Wenn dein OAuth / OIDC-Anbieter keine JWTs ausstellt oder du deine eigene Autorisierungslogik implementieren möchtest, erlaubt dir MCP Auth, eine benutzerdefinierte Überprüfungsfunktion zu erstellen:

info

Da das Bearer-Auth-Middleware den Aussteller (iss), die Zielgruppe (aud) und die erforderlichen Berechtigungen (scope) mit dem Überprüfungsergebnis abgleicht, musst du diese Prüfungen nicht in deiner benutzerdefinierten Überprüfungsfunktion implementieren. Du kannst dich darauf konzentrieren, die Token-Gültigkeit zu überprüfen (z. B. Signatur, Ablauf usw.) und das Auth-Info-Objekt zurückzugeben.

Python

from mcpauth.exceptions import MCPAuthJwtVerificationException, MCPAuthJwtVerificationExceptionCode
from mcpauth.types import AuthInfo

async def custom_verification(token: str) -> AuthInfo:
    # Implementiere hier deine benutzerdefinierte Überprüfungslogik
    info = await verify_token(token)
    if not info:
        raise MCPAuthJwtVerificationException(
            MCPAuthJwtVerificationExceptionCode.JWT_VERIFICATION_FAILED
        )
    return info  # Gib das Auth-Info-Objekt zurück

bearer_auth = mcp_auth.bearer_auth_middleware(
    custom_verification,
    resource="https://api.example.com",
    audience="https://api.example.com",  # Aktiviere die Zielgruppenvalidierung für Sicherheit
    required_scopes=["read", "write"]
)

Node.js

const bearerAuth = mcpAuth.bearerAuth(
  async (token) => {
    // Implementiere hier deine benutzerdefinierte Überprüfungslogik
    const info = await verifyToken(token);
    if (!info) {
      throw new MCPAuthJwtVerificationError('jwt_verification_failed');
    }
    return info; // Gib das Auth-Info-Objekt zurück
  },
  { 
    resource: 'https://api.example.com',
    audience: 'https://api.example.com', // Aktiviere die Zielgruppenvalidierung für Sicherheit
    requiredScopes: ['read', 'write'] 
  }
);

Bearer-Authentifizierung in deinem MCP-Server anwenden

Um deinen MCP-Server mit Bearer-Authentifizierung zu schützen, musst du das Bearer-Auth-Middleware auf deine MCP-Server-Instanz anwenden.

Python

bearer_auth = mcp_auth.bearer_auth_middleware("jwt", 
    resource="https://api.example.com",
    audience="https://api.example.com",  # Aktiviere die Zielgruppenvalidierung für Sicherheit
    required_scopes=["read", "write"]
)
app = Starlette(
    routes=[Mount('/', app=mcp.sse_app(), middleware=[Middleware(bearer_auth)])]
)

Node.js

const app = express();
app.use(mcpAuth.bearerAuth('jwt', { 
  resource: 'https://api.example.com',
  audience: 'https://api.example.com', // Aktiviere die Zielgruppenvalidierung für Sicherheit
  requiredScopes: ['read', 'write'] 
}));

Dadurch wird sichergestellt, dass alle eingehenden Anfragen gemäß den konfigurierten Bearer-Auth-Einstellungen authentifiziert und autorisiert werden und die Auth-Informationen im Request-Kontext verfügbar sind.

Du kannst die Informationen dann in deiner MCP-Server-Implementierung abrufen:

Python

@mcp.tool()
async def whoami() -> dict:
    # `mcp_auth.auth_info` ist das Kontextobjekt für die aktuelle Anfrage
    auth_info = mcp_auth.auth_info
    print(f"Authentifizierter Benutzer: {auth_info.subject}")
    return {"subject": auth_info.subject}

Node.js

// `authInfo` wird aus dem `req.auth`-Objekt übernommen
server.tool('whoami', ({ authInfo }) => {
  console.log(`Authentifizierter Benutzer: ${authInfo.subject}`);
  return { subject: authInfo.subject };
});