Aller au contenu principal
Version: 0.2.0-beta.1

Classe : MCPAuth

La classe principale de la bibliothèque mcp-auth. Elle agit comme une fabrique et un registre pour créer des politiques d’authentification pour vos ressources protégées.

Elle est initialisée avec vos configurations serveur et fournit une méthode bearerAuth pour générer un middleware Express pour l’authentification basée sur les jetons.

Exemple​

Utilisation en mode resource server​

C’est l’approche recommandée pour les nouvelles applications.

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` peut être un seul objet de configuration ou un tableau de ceux-ci.
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        authorizationServers: [authServerConfig],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

// Monter le routeur pour gérer les métadonnées des ressources protégées
app.use(mcpAuth.protectedResourceMetadataRouter());

// Protéger un point de terminaison API pour la ressource configurée
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier, // Spécifiez à quelle ressource ce point de terminaison appartient
    audience: resourceIdentifier, // Facultatif, valider la revendication 'aud'
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    console.log('Infos Auth :', req.auth);
    res.json({ notes: [] });
  },
);

Utilisation héritée en mode authorization server (Obsolète)​

Cette approche est prise en charge pour la rétrocompatibilité.

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' }
  ),
});

// Monter le routeur pour gérer les métadonnées héritées du serveur d’autorisation
app.use(mcpAuth.delegatedRouter());

// Protéger un point de terminaison en utilisant la politique par défaut
app.get(
  '/mcp',
  mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }),
  (req, res) => {
    console.log('Infos Auth :', req.auth);
    // Traiter la requête MCP ici
  },
);

Constructeurs​

Constructeur​

new MCPAuth(config: MCPAuthConfig): MCPAuth;

Crée une instance de MCPAuth. Elle valide toute la configuration en amont pour échouer rapidement en cas d’erreur.

Paramètres​

config​

MCPAuthConfig

La configuration d’authentification.

Retourne​

MCPAuth

Propriétés​

config​

readonly config: MCPAuthConfig;

La configuration d’authentification.

Méthodes​

bearerAuth()​

Signature d’appel​

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

Crée un gestionnaire d’authentification Bearer (middleware Express) qui vérifie le jeton d’accès dans l’en-tête Authorization de la requête.

Paramètres​
verifyAccessToken​

VerifyAccessTokenFunction

Une fonction qui vérifie le jeton d’accès. Elle doit accepter le jeton d’accès sous forme de chaîne et retourner une promesse (ou une valeur) qui se résout avec le résultat de la vérification.

Voir

VerifyAccessTokenFunction pour la définition du type de la fonction verifyAccessToken.

config?​

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

Configuration optionnelle pour le gestionnaire d’authentification Bearer.

Voir

BearerAuthConfig pour les options de configuration disponibles (à l’exception de verifyAccessToken et issuer).

Retourne​

RequestHandler

Une fonction middleware Express qui vérifie le jeton d’accès et ajoute le résultat de la vérification à l’objet requête (req.auth).

Voir​

handleBearerAuth pour les détails d’implémentation et les types étendus de l’objet req.auth (AuthInfo).

Signature d’appel​

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

Crée un gestionnaire d’authentification Bearer (middleware Express) qui vérifie le jeton d’accès dans l’en-tête Authorization de la requête en utilisant un mode de vérification prédéfini.

En mode 'jwt', le gestionnaire créera une fonction de vérification JWT en utilisant le JWK Set depuis l’URI JWKS du serveur d’autorisation.

Paramètres​
mode​

"jwt"

Le mode de vérification pour le jeton d’accès. Actuellement, seul 'jwt' est pris en charge.

Voir

VerifyAccessTokenMode pour les modes disponibles.

config?​

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

Configuration optionnelle pour le gestionnaire d’authentification Bearer, incluant les options de vérification JWT et les options du JWK Set distant.

Voir

  • VerifyJwtConfig pour les options de configuration disponibles pour la vérification JWT.
  • BearerAuthConfig pour les options de configuration disponibles (à l’exception de verifyAccessToken et issuer).
Retourne​

RequestHandler

Une fonction middleware Express qui vérifie le jeton d’accès et ajoute le résultat de la vérification à l’objet requête (req.auth).

Voir​

handleBearerAuth pour les détails d’implémentation et les types étendus de l’objet req.auth (AuthInfo).

Lève​

si l’URI JWKS n’est pas fourni dans les métadonnées du serveur lors de l’utilisation du mode 'jwt'.

delegatedRouter()​

delegatedRouter(): Router;

Crée un routeur délégué pour servir le point de terminaison hérité OAuth 2.0 Authorization Server Metadata (/.well-known/oauth-authorization-server) avec les métadonnées fournies à l’instance.

Retourne​

Router

Un routeur qui sert le point de terminaison OAuth 2.0 Authorization Server Metadata avec les métadonnées fournies à l’instance.

Obsolète​

Utilisez protectedResourceMetadataRouter à la place.

Exemple​

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

const app = express();
const mcpAuth: MCPAuth; // Supposons que ceci est initialisé
app.use(mcpAuth.delegatedRouter());

Lève​

Si appelé en mode resource server.

protectedResourceMetadataRouter()​

protectedResourceMetadataRouter(): Router;

Crée un routeur qui sert le point de terminaison OAuth 2.0 Protected Resource Metadata pour toutes les ressources configurées.

Ce routeur crée automatiquement les bons points de terminaison .well-known pour chaque identifiant de ressource fourni dans votre configuration.

Retourne​

Router

Un routeur qui sert le point de terminaison OAuth 2.0 Protected Resource Metadata.

Lève​

Si appelé en mode authorization server.

Exemple​

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

// Supposons que mcpAuth est initialisé avec une ou plusieurs configurations `protectedResources`
const mcpAuth: MCPAuth;
const app = express();

// Cela servira les métadonnées à `/.well-known/oauth-protected-resource/...`
// selon vos identifiants de ressources.
app.use(mcpAuth.protectedResourceMetadataRouter());