Aller au contenu principal

Tutoriel : Qui suis-je ? (Tutorial: Who am I?)

Ce tutoriel vous guidera à travers le processus de configuration de MCP Auth pour authentifier les utilisateurs et récupérer leurs informations d'identité depuis le serveur d’autorisation (Authorization Server).

Après avoir terminé ce tutoriel, vous aurez :

  • ✅ Une compréhension de base de l’utilisation de MCP Auth pour authentifier les utilisateurs.
  • ✅ Un serveur MCP qui offre un outil pour récupérer les informations d'identité utilisateur.

Vue d’ensemble​

Le tutoriel impliquera les composants suivants :

  • Serveur MCP : Un serveur MCP simple qui utilise les SDK officiels MCP pour gérer les requêtes.
  • Inspecteur MCP : Un outil de test visuel pour les serveurs MCP. Il agit également comme un client OAuth / OIDC pour initier le flux d’autorisation et récupérer les jetons d’accès (Access tokens).
  • Serveur d’autorisation (Authorization server) : Un fournisseur OAuth 2.1 ou OpenID Connect qui gère les identités utilisateur et émet les jetons d’accès (Access tokens).

Voici un schéma de haut niveau de l’interaction entre ces composants :

Comprendre votre serveur d’autorisation​

Récupérer les informations d'identité utilisateur​

Pour compléter ce tutoriel, votre serveur d’autorisation doit offrir une API pour récupérer les informations d'identité utilisateur :

Logto est un fournisseur OpenID Connect qui prend en charge l’endpoint userinfo standard pour récupérer les informations d'identité utilisateur.

Pour obtenir un jeton d’accès (Access token) utilisable sur l’endpoint userinfo, au moins deux portées (Scopes) sont requises : openid et profile. Vous pouvez continuer à lire, car nous aborderons la configuration des portées plus loin.

Enregistrement dynamique du client​

L’enregistrement dynamique du client n’est pas requis pour ce tutoriel, mais il peut être utile si vous souhaitez automatiser le processus d’enregistrement du client MCP auprès de votre serveur d’autorisation. Consultez L’enregistrement dynamique du client est-il requis ? pour plus de détails.

Configurer le serveur MCP​

Nous allons utiliser les SDK officiels MCP pour créer un serveur MCP avec un outil whoami qui récupère les informations d'identité utilisateur depuis le serveur d’autorisation.

Créer un nouveau projet​

mkdir mcp-server
cd mcp-server
uv init # Ou utilisez `pipenv` ou `poetry` pour créer un nouvel environnement virtuel

Installer le SDK MCP et les dépendances​

pip install "mcp[cli]" starlette uvicorn

Ou tout autre gestionnaire de paquets que vous préférez, comme uv ou poetry.

Créer le serveur MCP​

Commençons par créer un serveur MCP qui implémente un outil whoami.

Créez un fichier nommé whoami.py et ajoutez le code suivant :

from mcp.server.fastmcp import FastMCP
from starlette.applications import Starlette
from starlette.routing import Mount
from typing import Any

mcp = FastMCP("WhoAmI")

@mcp.tool()
def whoami() -> dict[str, Any]:
    """Un outil qui retourne les informations de l’utilisateur courant."""
    return {"error": "Not authenticated"}

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

Lancez le serveur avec :

uvicorn whoami:app --host 0.0.0.0 --port 3001

Inspecter le serveur MCP​

Cloner et lancer l’inspecteur MCP​

Maintenant que le serveur MCP fonctionne, nous pouvons utiliser l’inspecteur MCP pour vérifier si l’outil whoami est disponible.

En raison des limites de l’implémentation actuelle, nous avons forké l’inspecteur MCP pour le rendre plus flexible et évolutif pour l’authentification (Authentication) et l’autorisation (Authorization). Nous avons également soumis une pull request au dépôt original pour inclure nos modifications.

Pour lancer l’inspecteur MCP, vous pouvez utiliser la commande suivante (Node.js est requis) :

git clone https://github.com/mcp-auth/inspector.git
cd inspector
npm install
npm run dev

Ensuite, ouvrez votre navigateur et accédez à http://localhost:6274/ (ou à l’URL affichée dans le terminal) pour accéder à l’inspecteur MCP.

Connecter l’inspecteur MCP au serveur MCP​

Avant de continuer, vérifiez la configuration suivante dans l’inspecteur MCP :

  • Type de transport : Réglez sur SSE.
  • URL : Réglez sur l’URL de votre serveur MCP. Dans notre cas, il s’agit de http://localhost:3001/sse.

Vous pouvez maintenant cliquer sur le bouton "Connecter" pour voir si l’inspecteur MCP peut se connecter au serveur MCP. Si tout est correct, vous devriez voir le statut "Connecté" dans l’inspecteur MCP.

Point de contrôle : Exécuter l’outil whoami​

  1. Dans le menu supérieur de l’inspecteur MCP, cliquez sur l’onglet "Outils".
  2. Cliquez sur le bouton "Lister les outils".
  3. Vous devriez voir l’outil whoami listé sur la page. Cliquez dessus pour ouvrir les détails de l’outil.
  4. Vous devriez voir le bouton "Exécuter l’outil" à droite. Cliquez dessus pour exécuter l’outil.
  5. Vous devriez voir le résultat de l’outil avec la réponse JSON {"error": "Not authenticated"}.

Première exécution de l’inspecteur MCP

Intégrer avec votre serveur d’autorisation​

Pour compléter cette section, plusieurs points sont à prendre en compte :

L’URL de l’émetteur (Issuer) de votre serveur d’autorisation

Il s’agit généralement de l’URL de base de votre serveur d’autorisation, comme https://auth.example.com. Certains fournisseurs peuvent avoir un chemin comme https://example.logto.app/oidc, alors assurez-vous de vérifier la documentation de votre fournisseur.

Comment récupérer les métadonnées du serveur d’autorisation
  • Si votre serveur d’autorisation est conforme à la spécification OAuth 2.0 Authorization Server Metadata ou à OpenID Connect Discovery, vous pouvez utiliser les utilitaires intégrés de MCP Auth pour récupérer automatiquement les métadonnées.
  • Si votre serveur d’autorisation n’est pas conforme à ces standards, vous devrez spécifier manuellement l’URL des métadonnées ou les endpoints dans la configuration du serveur MCP. Consultez la documentation de votre fournisseur pour les endpoints spécifiques.
Comment enregistrer l’inspecteur MCP comme client dans votre serveur d’autorisation
  • Si votre serveur d’autorisation prend en charge l’enregistrement dynamique du client, vous pouvez ignorer cette étape car l’inspecteur MCP s’enregistrera automatiquement comme client.
  • Si votre serveur d’autorisation ne prend pas en charge l’enregistrement dynamique du client, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre serveur d’autorisation.
Comment récupérer les informations d'identité utilisateur et comment configurer les paramètres de la requête d’autorisation

  • Pour les fournisseurs OpenID Connect : généralement, vous devez demander au moins les portées (Scopes) openid et profile lors de l’initiation du flux d’autorisation. Cela garantira que le jeton d’accès (Access token) retourné par le serveur d’autorisation contient les portées nécessaires pour accéder à l’endpoint userinfo et récupérer les informations d'identité utilisateur.

    Remarque : certains fournisseurs peuvent ne pas prendre en charge l’endpoint userinfo.

  • Pour les fournisseurs OAuth 2.0 / OAuth 2.1 : consultez la documentation de votre fournisseur pour savoir comment récupérer les informations d'identité utilisateur à l’aide d’un jeton d’accès (Access token) et quels paramètres sont requis pour obtenir ce jeton lors de l’appel du flux d’autorisation.

Bien que chaque fournisseur puisse avoir ses propres exigences spécifiques, les étapes suivantes vous guideront dans le processus d’intégration de l’inspecteur MCP et du serveur MCP avec des configurations spécifiques au fournisseur.

Enregistrer l’inspecteur MCP comme client​

L’intégration avec Logto est simple puisqu’il s’agit d’un fournisseur OpenID Connect qui prend en charge l’endpoint userinfo standard pour récupérer les informations d'identité utilisateur.

Comme Logto ne prend pas encore en charge l’enregistrement dynamique du client, vous devrez enregistrer manuellement l’inspecteur MCP comme client dans votre tenant Logto :

  1. Ouvrez votre inspecteur MCP, cliquez sur le bouton "Configuration OAuth". Copiez la valeur Redirect URL (auto-populated), qui devrait ressembler à http://localhost:6274/oauth/callback.
  2. Connectez-vous à Logto Console (ou à votre Logto Console auto-hébergée).
  3. Accédez à l’onglet "Applications", cliquez sur "Créer une application". En bas de la page, cliquez sur "Créer une application sans framework".
  4. Remplissez les détails de l’application, puis cliquez sur "Créer l’application" :
    • Sélectionnez un type d’application : Choisissez "Application monopage".
    • Nom de l’application : Entrez un nom pour votre application, par exemple "MCP Inspector".
  5. Dans la section "Paramètres / URI de redirection", collez la valeur Redirect URL (auto-populated) copiée depuis l’inspecteur MCP. Cliquez ensuite sur "Enregistrer les modifications" dans la barre du bas.
  6. Dans la carte du haut, vous verrez la valeur "App ID". Copiez-la.
  7. Retournez dans l’inspecteur MCP et collez la valeur "App ID" dans la section "Configuration OAuth" sous "Client ID".
  8. Entrez la valeur {"scope": "openid profile email"} dans le champ "Auth Params". Cela garantira que le jeton d’accès (Access token) retourné par Logto contient les portées nécessaires pour accéder à l’endpoint userinfo.

Configurer MCP Auth​

Dans votre projet serveur MCP, vous devez installer le SDK MCP Auth et le configurer pour utiliser les métadonnées de votre serveur d’autorisation.

D’abord, installez le paquet mcpauth :

pip install mcpauth

Ou tout autre gestionnaire de paquets que vous préférez, comme uv ou poetry.

MCP Auth nécessite les métadonnées du serveur d’autorisation pour pouvoir s’initialiser. Selon votre fournisseur :

L’URL de l’émetteur (Issuer) se trouve sur la page de détails de votre application dans Logto Console, dans la section "Endpoints & Credentials / Issuer endpoint". Elle devrait ressembler à https://my-project.logto.app/oidc.

Mettez à jour le fichier whoami.py pour inclure la configuration MCP Auth :

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

auth_issuer = '<issuer-endpoint>'  # Remplacez par votre endpoint d’émetteur
auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC)
mcp_auth = MCPAuth(server=auth_server_config)

Nous devons maintenant créer un vérificateur personnalisé de jeton d’accès (Access token) qui ira chercher les informations d'identité de l'utilisateur auprès du serveur d'autorisation en utilisant le jeton d’accès fourni par l’inspecteur MCP.

import pydantic
import requests
from mcpauth.exceptions import (
    MCPAuthTokenVerificationException,
    MCPAuthTokenVerificationExceptionCode,
)
from mcpauth.types import AuthInfo

def verify_access_token(token: str) -> AuthInfo:
    """
    Vérifie le jeton Bearer fourni en récupérant les informations utilisateur depuis le serveur d'autorisation.
    Si le jeton est valide, retourne un objet `AuthInfo` contenant les informations de l'utilisateur.

    :param token: Le jeton Bearer reçu de l’inspecteur MCP.
    """

    issuer = auth_server_config.metadata.issuer
    endpoint = auth_server_config.metadata.userinfo_endpoint # Le fournisseur doit supporter l’endpoint userinfo
    if not endpoint:
        raise ValueError(
            "L’endpoint userinfo n’est pas configuré dans les métadonnées du serveur d’authentification."
        )

    try:
        response = requests.get(
            endpoint,
            headers={"Authorization": f"Bearer {token}"}, # En-tête standard Bearer token
        )
        response.raise_for_status() # S’assurer de lever une erreur pour les erreurs HTTP
        json = response.json() # Analyse la réponse JSON
        return AuthInfo(
            token=token,
            subject=json.get("sub"), # 'sub' est une revendication standard pour le sujet (ID utilisateur)
            issuer=issuer, # Utilise l’émetteur issu des métadonnées
            claims=json, # Inclut toutes les revendications (champs JSON) retournées par l’endpoint userinfo
        )
    # `AuthInfo` est un modèle Pydantic, donc les erreurs de validation signifient généralement que la réponse ne correspond pas
    # à la structure attendue
    except pydantic.ValidationError as e:
        raise MCPAuthTokenVerificationException(
            MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN,
            cause=e,
        )
    # Gérer les autres exceptions pouvant survenir lors de la requête
    except Exception as e:
        raise MCPAuthTokenVerificationException(
            MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED,
            cause=e,
        )

Mettre à jour le serveur MCP​

Nous y sommes presque ! Il est temps de mettre à jour le serveur MCP pour appliquer la route MCP Auth et la fonction middleware, puis faire en sorte que l’outil whoami retourne les véritables informations d'identité utilisateur.

@mcp.tool()
def whoami() -> dict[str, Any]:
    """Un outil qui retourne les informations de l’utilisateur courant."""
    return (
        mcp_auth.auth_info.claims
        if mcp_auth.auth_info # Ceci sera renseigné par le middleware Bearer auth
        else {"error": "Not authenticated"}
    )

# ...

bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token))
app = Starlette(
    routes=[
        # Ajoutez la route des métadonnées (`/.well-known/oauth-authorization-server`)
        mcp_auth.metadata_route(),
        # Protégez le serveur MCP avec le middleware Bearer auth
        Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]),
    ],
)

Point de contrôle : Exécuter l’outil whoami avec authentification​

Redémarrez votre serveur MCP et ouvrez l’inspecteur MCP dans votre navigateur. Lorsque vous cliquez sur le bouton "Connecter", vous devriez être redirigé vers la page de connexion de votre serveur d’autorisation.

Une fois connecté et de retour dans l’inspecteur MCP, répétez les actions du point de contrôle précédent pour exécuter l’outil whoami. Cette fois, vous devriez voir les informations d'identité utilisateur retournées par le serveur d’autorisation.

Résultat de l’outil whoami dans l’inspecteur MCP

info

Consultez le dépôt du SDK MCP Auth Python pour le code complet du serveur MCP (version OIDC).

Notes de clôture​

🎊 Félicitations ! Vous avez terminé avec succès le tutoriel. Récapitulons ce que nous avons fait :

  • Mise en place d’un serveur MCP basique avec l’outil whoami
  • Intégration du serveur MCP avec un serveur d’autorisation via MCP Auth
  • Configuration de l’inspecteur MCP pour authentifier les utilisateurs et récupérer leurs informations d'identité

Vous pouvez également explorer des sujets avancés, notamment :

N’hésitez pas à consulter d’autres tutoriels et la documentation pour tirer le meilleur parti de MCP Auth.