Aller au contenu principal

Commencer

Prise en charge de la spécification d’autorisation MCP

Cette version prend en charge la spécification d’autorisation MCP (version 2025-06-18).

SDK Python disponible

MCP Auth est également disponible pour Python ! Consultez le dépôt SDK Python pour l’installation et l’utilisation.

Choisir un fournisseur compatible OAuth 2.1 ou OpenID Connect​

La spécification MCP comporte des exigences spécifiques pour l’autorisation. Le mécanisme d’autorisation repose sur des spécifications établies, en implémentant un sous-ensemble sélectionné de leurs fonctionnalités afin de garantir la sécurité et l’interopérabilité tout en maintenant la simplicité :

  • OAuth 2.1 IETF DRAFT (draft-ietf-oauth-v2-1-13)
  • Métadonnées du serveur d’autorisation OAuth 2.0 (RFC 8414)
  • Protocole d’enregistrement dynamique de client OAuth 2.0 (RFC 7591)
  • Métadonnées de ressource protégée OAuth 2.0 (RFC 9728)

Ces spécifications fonctionnent ensemble pour fournir un cadre d’autorisation sécurisé et standardisé pour les implémentations MCP.

Vous pouvez consulter la liste des fournisseurs compatibles MCP pour vérifier si votre fournisseur est pris en charge.

Installer le SDK MCP Auth​

pnpm add mcp-auth

Initialiser MCP Auth​

La première étape consiste à définir votre identifiant de ressource et à configurer le serveur d’autorisation qui sera approuvé pour l’authentification. MCP Auth fonctionne désormais en mode serveur de ressource, conformément à la spécification MCP mise à jour qui exige les métadonnées de ressource protégée OAuth 2.0 (RFC 9728).

Si votre fournisseur est conforme à :

Vous pouvez utiliser la fonction intégrée pour récupérer les métadonnées et initialiser l’instance MCP Auth :

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

// 1. Définissez votre identifiant de ressource et récupérez la configuration pour son serveur d’autorisation de confiance.
const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

// 2. Initialisez MCPAuth en mode serveur de ressource.
// `protectedResources` peut être un objet unique ou un tableau pour plusieurs ressources.
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceIdentifier,
      authorizationServers: [authServerConfig],
      scopesSupported: ['read:notes', 'write:notes'],
    },
  },
});

Si vous utilisez des environnements edge comme Cloudflare Workers où l’appel async de haut niveau n’est pas autorisé, utilisez la découverte à la demande à la place :

const authServerConfig = { issuer: 'https://auth.logto.io/oidc', type: 'oidc' };

Pour d’autres façons de configurer les métadonnées du serveur d’autorisation, y compris les URLs de métadonnées personnalisées, la transpilation de données ou la spécification manuelle des métadonnées, consultez Autres façons de configurer MCP Auth.

Monter l’endpoint des métadonnées de ressource protégée​

Pour se conformer à la spécification MCP mise à jour, MCP Auth monte l’endpoint des métadonnées de ressource protégée OAuth 2.0 (RFC 9728) sur votre serveur MCP. Cet endpoint permet aux clients de découvrir :

  • Quels serveurs d’autorisation peuvent émettre des jetons valides pour vos ressources protégées
  • Quelles portées sont prises en charge pour chaque ressource
  • D’autres métadonnées nécessaires à une validation correcte des jetons

Le chemin de l’endpoint est automatiquement déterminé par le composant chemin de votre identifiant de ressource :

  • Sans chemin : https://api.example.com → /.well-known/oauth-protected-resource
  • Avec chemin : https://api.example.com/notes → /.well-known/oauth-protected-resource/notes

Le serveur MCP agit désormais comme un serveur de ressource qui valide les jetons et fournit des métadonnées sur ses ressources protégées, tout en s’appuyant entièrement sur des serveurs d’autorisation externes pour l’authentification et l’autorisation.

Vous pouvez utiliser la méthode fournie par le SDK pour monter cet endpoint :

import express from 'express';

const app = express();

// Montez le routeur pour servir les métadonnées de ressource protégée.
// Pour la ressource "https://api.example.com" → endpoint : /.well-known/oauth-protected-resource
// Pour la ressource "https://api.example.com/notes" → endpoint : /.well-known/oauth-protected-resource/notes
app.use(mcpAuth.protectedResourceMetadataRouter());

Utiliser le middleware d’authentification Bearer​

Une fois l’instance MCP Auth initialisée, vous pouvez appliquer le middleware d’authentification Bearer pour protéger vos routes MCP. Le middleware nécessite désormais de spécifier à quelle ressource appartient l’endpoint, permettant ainsi une validation correcte du jeton :

Validation de l’audience

Le paramètre audience est requis par la spécification OAuth 2.0 pour une validation sécurisée du jeton. Cependant, il est actuellement optionnel afin de maintenir la compatibilité avec les serveurs d’autorisation qui ne prennent pas encore en charge les identifiants de ressource. Pour des raisons de sécurité, veuillez toujours inclure le paramètre audience lorsque cela est possible. Les futures versions rendront la validation de l’audience obligatoire pour se conformer pleinement à la spécification.

Toujours valider les portées

Dans OAuth 2.0, les portées (Scopes) sont le principal mécanisme de contrôle des permissions. Un jeton valide avec la bonne audience ne garantit PAS que l'utilisateur a la permission d'effectuer une action — les serveurs d'autorisation peuvent émettre des jetons avec une portée vide ou limitée.

Utilisez toujours requiredScopes pour vous assurer que le jeton contient les permissions nécessaires pour chaque opération. Ne supposez jamais qu'un jeton valide implique un accès complet.

import express from 'express';

const app = express();

// Montez le routeur pour servir les métadonnées de ressource protégée.
app.use(mcpAuth.protectedResourceMetadataRouter());

// Protégez un endpoint API en utilisant la politique spécifique à la ressource.
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier,
    audience: resourceIdentifier,  // Activez la validation de l’audience pour la sécurité
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    // Si le jeton est valide, `req.auth` est rempli avec ses revendications.
    console.log('Infos Auth :', req.auth);
    res.json({ notes: [] });
  },
);

app.listen(3000);

Dans les exemples ci-dessus, nous spécifions le type de jeton jwt et l’identifiant de ressource. Le middleware validera automatiquement le jeton JWT auprès des serveurs d’autorisation de confiance configurés pour cette ressource spécifique et remplira les informations de l’utilisateur authentifié.

info

Jamais entendu parler de JWT (JSON Web Token) auparavant ? Pas d’inquiétude, vous pouvez continuer à lire la documentation et nous l’expliquerons en temps voulu. Vous pouvez également consulter Auth Wiki pour une introduction rapide.

Pour plus d’informations sur la configuration de l’authentification Bearer, consultez Configurer l’authentification Bearer.

Récupérer les informations d’authentification dans votre implémentation MCP​

Une fois le middleware d’authentification Bearer appliqué, vous pouvez accéder aux informations de l’utilisateur (ou de l’identité) authentifié dans votre implémentation MCP :

Le second argument du gestionnaire d’outil contiendra l’objet authInfo, qui inclut les informations de l’utilisateur authentifié :

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer(/* ... */);

// Initialisez avec MCP Auth comme montré dans les exemples précédents
// ...

server.registerTool(
  'add',
  {
    description: 'Additionner deux nombres',
    inputSchema: { a: z.number(), b: z.number() },
  },
  async ({ a, b }, { authInfo }) => {
    // Vous pouvez maintenant utiliser l’objet `authInfo` pour accéder aux informations authentifiées
  }
);

Prochaines étapes​

Continuez la lecture pour découvrir un exemple de bout en bout sur la façon d’intégrer MCP Auth à votre serveur MCP, et comment gérer le flux d’authentification dans les clients MCP.