Klasse: MCPAuth

Die Hauptklasse für die 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.

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` kann ein einzelnes Konfigurationsobjekt oder ein Array davon sein.
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        authorizationServers: [authServerConfig],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

// 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: Überprüfe den 'aud'-Anspruch
    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, fetchServerConfig } from 'mcp-auth';

const app = express();
const mcpAuth = new MCPAuth({
  server: await fetchServerConfig(
    '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);
    // Bearbeite hier die MCP-Anfrage
  },
);

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 (außer 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 Details zur Implementierung 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 Autorisierungsservers.

Parameter

mode

"jwt"

Der Verifizierungsmodus für das Zugangstoken (Access token). Aktuell 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 (außer 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 Details zur Implementierung und die erweiterten Typen des req.auth (AuthInfo)-Objekts.

Fehler

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

---

delegatedRouter()

delegatedRouter(): Router;

Erstellt einen Delegated Router zum Bereitstellen des veralteten OAuth 2.0 Authorization Server Metadata Endpunkts (/.well-known/oauth-authorization-server) mit den der Instanz bereitgestellten Metadaten.

Rückgabewert

Router

Ein Router, der den OAuth 2.0 Authorization Server Metadata Endpunkt mit den bereitgestellten Metadaten der Instanz bedient.

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());

Fehler

Wenn im Resource Server-Modus aufgerufen.

---

protectedResourceMetadataRouter()

protectedResourceMetadataRouter(): Router;

Erstellt einen Router, der den OAuth 2.0 Protected Resource Metadata Endpunkt 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 Endpunkt bereitstellt.

Fehler

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());