Zum Hauptinhalt springen

Klasse: MCPAuth

Die Hauptklasse der mcp-auth-Bibliothek. Sie fungiert als Factory und Registry zur Erstellung von Authentifizierungsrichtlinien für deine geschützten Ressourcen.

Sie wird mit deinen Serverkonfigurationen initialisiert und stellt eine bearerAuth-Methode bereit, um Express-Middleware für tokenbasierte Authentifizierung zu generieren.

Beispiel​

Verwendung im Resource Server-Modus​

Dies ist der empfohlene Ansatz für neue Anwendungen.

Verwende dies, wenn Metadaten bei Bedarf abgerufen werden sollen. Dies ist besonders nützlich für Edge-Runtimes wie Cloudflare Workers, bei denen asynchrone Fetch-Operationen auf Top-Level-Ebene nicht erlaubt sind.

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

const app = express();
const resourceIdentifier = 'https://api.example.com/notes';

const mcpAuth = new MCPAuth({
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        // Nur issuer und type angeben – Metadaten werden bei der ersten Anfrage abgerufen
        authorizationServers: [{ issuer: 'https://auth.logto.io/oidc', type: 'oidc' }],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

Option 2: Resolved-Konfiguration (vorgefetchte Metadaten)​

Verwende dies, wenn du Metadaten beim Start abrufen und validieren möchtest.

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

const app = express();
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

const mcpAuth = new MCPAuth({
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        authorizationServers: [authServerConfig],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

Verwendung der Middleware​

// Router für Protected Resource Metadata einbinden
app.use(mcpAuth.protectedResourceMetadataRouter());

// Einen API-Endpunkt für die konfigurierte Ressource schützen
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier, // Gibt an, zu welcher Ressource dieser Endpunkt gehört
    audience: resourceIdentifier, // Optional: das 'aud'-Claim validieren
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

Legacy-Verwendung im Authorization Server-Modus (Veraltet)​

Dieser Ansatz wird aus Gründen der Abwärtskompatibilität unterstützt.

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

const app = express();
const mcpAuth = new MCPAuth({
  // Discovery-Konfiguration – Metadaten werden bei Bedarf abgerufen
  server: { issuer: 'https://auth.logto.io/oidc', type: 'oidc' },
});

// Router für Legacy Authorization Server Metadata einbinden
app.use(mcpAuth.delegatedRouter());

// Einen Endpunkt mit der Standardrichtlinie schützen
app.get(
  '/mcp',
  mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    // Hier die MCP-Anfrage bearbeiten
  },
);

Konstruktoren​

Konstruktor​

new MCPAuth(config: MCPAuthConfig): MCPAuth;

Erstellt eine Instanz von MCPAuth. Die gesamte Konfiguration wird im Voraus validiert, um Fehler frühzeitig zu erkennen.

Parameter​

config​

MCPAuthConfig

Die Authentifizierungskonfiguration.

Rückgabewert​

MCPAuth

Eigenschaften​

config​

readonly config: MCPAuthConfig;

Die Authentifizierungskonfiguration.

Methoden​

bearerAuth()​

Aufrufsignatur​

bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">): RequestHandler;

Erstellt einen Bearer-Auth-Handler (Express-Middleware), der das Zugangstoken (Access token) im Authorization-Header der Anfrage überprüft.

Parameter​
verifyAccessToken​

VerifyAccessTokenFunction

Eine Funktion, die das Zugangstoken (Access token) überprüft. Sie sollte das Zugangstoken als String akzeptieren und ein Promise (oder einen Wert) zurückgeben, das/die das Überprüfungsergebnis liefert.

Siehe

VerifyAccessTokenFunction für die Typdefinition der verifyAccessToken-Funktion.

config?​

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">

Optionale Konfiguration für den Bearer-Auth-Handler.

Siehe

BearerAuthConfig für die verfügbaren Konfigurationsoptionen (ohne verifyAccessToken und issuer).

Rückgabewert​

RequestHandler

Eine Express-Middleware-Funktion, die das Zugangstoken (Access token) überprüft und das Überprüfungsergebnis dem Request-Objekt (req.auth) hinzufügt.

Siehe​

handleBearerAuth für die Implementierungsdetails und die erweiterten Typen des req.auth (AuthInfo) Objekts.

Aufrufsignatur​

bearerAuth(mode: "jwt", config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig): RequestHandler;

Erstellt einen Bearer-Auth-Handler (Express-Middleware), der das Zugangstoken (Access token) im Authorization-Header der Anfrage mit einem vordefinierten Verifizierungsmodus überprüft.

Im 'jwt'-Modus erstellt der Handler eine JWT-Überprüfungsfunktion unter Verwendung des JWK-Sets von der JWKS-URI des Authorization Servers.

Parameter​
mode​

"jwt"

Der Verifizierungsmodus für das Zugangstoken (Access token). Derzeit wird nur 'jwt' unterstützt.

Siehe

VerifyAccessTokenMode für die verfügbaren Modi.

config?​

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig

Optionale Konfiguration für den Bearer-Auth-Handler, einschließlich JWT-Überprüfungsoptionen und Remote-JWK-Set-Optionen.

Siehe

  • VerifyJwtConfig für die verfügbaren Konfigurationsoptionen für die JWT- Überprüfung.
  • BearerAuthConfig für die verfügbaren Konfigurationsoptionen (ohne verifyAccessToken und issuer).
Rückgabewert​

RequestHandler

Eine Express-Middleware-Funktion, die das Zugangstoken (Access token) überprüft und das Überprüfungsergebnis dem Request-Objekt (req.auth) hinzufügt.

Siehe​

handleBearerAuth für die Implementierungsdetails und die erweiterten Typen des req.auth (AuthInfo) Objekts.

Wirft​

wenn die JWKS-URI in den Server-Metadaten nicht angegeben ist, wenn der 'jwt'-Modus verwendet wird.

delegatedRouter()​

delegatedRouter(): Router;

Erstellt einen Delegated Router, um den veralteten OAuth 2.0 Authorization Server Metadata Endpoint (/.well-known/oauth-authorization-server) mit den der Instanz bereitgestellten Metadaten bereitzustellen.

Rückgabewert​

Router

Ein Router, der den OAuth 2.0 Authorization Server Metadata Endpoint mit den der Instanz bereitgestellten Metadaten bereitstellt.

Veraltet​

Verwende stattdessen protectedResourceMetadataRouter.

Beispiel​

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

const app = express();
const mcpAuth: MCPAuth; // Angenommen, dies ist initialisiert
app.use(mcpAuth.delegatedRouter());

Wirft​

Wenn im Resource Server-Modus aufgerufen.

protectedResourceMetadataRouter()​

protectedResourceMetadataRouter(): Router;

Erstellt einen Router, der den OAuth 2.0 Protected Resource Metadata Endpoint für alle konfigurierten Ressourcen bereitstellt.

Dieser Router erstellt automatisch die korrekten .well-known-Endpunkte für jede Ressourcenkennung, die in deiner Konfiguration angegeben ist.

Rückgabewert​

Router

Ein Router, der den OAuth 2.0 Protected Resource Metadata Endpoint bereitstellt.

Wirft​

Wenn im Authorization Server-Modus aufgerufen.

Beispiel​

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

// Angenommen, mcpAuth ist mit einer oder mehreren `protectedResources`-Konfigurationen initialisiert
const mcpAuth: MCPAuth;
const app = express();

// Dies stellt Metadaten unter `/.well-known/oauth-protected-resource/...` bereit
// basierend auf deinen Ressourcenkennungen.
app.use(mcpAuth.protectedResourceMetadataRouter());