Aller au contenu
English

Intégration d'OAuth

  • Leçon 16
  • 55 min
  • Module 5 : Accès à distance et autorisation

Où nous en sommes

Dans les deux leçons précédentes, nous avons exposé le serveur avec HTTP et décidé sur le serveur ce que chaque appelant peut faire. Mais jusqu'ici, les jetons venaient d'un raccourci d'exercice. Dans cette leçon, nous suivons la voie officielle par laquelle tout client MCP obtient un jeton pour notre serveur : métadonnées, connexion avec PKCE et audience. Nous commençons par une carte d'accès dans un hôtel que vous n'avez jamais visité.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

Ce que vous saurez faire

Permettez à tout client MCP d’obtenir un jeton pour le serveur de Larkfield par la voie officielle, sans raccourci. Vous suivez le flux étape par étape : réponse 401 du serveur, deux documents de métadonnées, inscription, connexion avec PKCE et jeton pour ce serveur. Ensuite, vous observez le client de la trousse SDK faire tout cela en un seul appel. Vous corrigez ensuite les portées qu’il a demandées.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 55 minutes

Ce que vous devez savoir

Votre projet

  • ~/projects/support-mcp après Identité et autorisations : python -m pytest -q affiche 63 passed (63 tests réussis).
  • Le terminal 1 exécute python -m idp, le terminal 2 exécute python -m support_mcp --http.
  • Les étapes manuelles utilisent un interpréteur de commandes macOS ou Linux. Sous Windows, utilisez Git Bash ou WSL pour ces étapes (non testé), ou passez à python -m scripts.oauth_login.

Une carte d’accès dans un hôtel que vous n’avez jamais visité

Section intitulée « Une carte d’accès dans un hôtel que vous n’avez jamais visité »

Le cours sur l’authentification utilisait un hôtel. La réception vérifie votre passeport et vous donne une carte d’accès. La carte ouvre la chambre 214 et la salle d’entraînement. Elle cesse de fonctionner quand vous quittez l’hôtel. La porte ne voit jamais votre passeport; elle vérifie seulement la carte.

Imaginez maintenant une personne qui arrive dans un hôtel qu’elle ne connaît pas. Elle trouve une porte verrouillée. Une affiche sur la porte indique quelle réception délivre ses cartes. À cette réception, un panneau présente les services : où se connecter, où récupérer la carte. La personne donne son nom une fois et reçoit un numéro de client. Ensuite, elle se connecte et reçoit une carte pour cette seule porte. L’exemple des chiffres du numéro de téléphone du cours sur l’authentification s’applique toujours. La personne qui récupère la carte doit prouver qu’elle a lancé la demande.

Jusqu’ici, les jetons provenaient de python -m idp token, un raccourci d’exercice sur le même ordinateur. L’application partenaire d’Omar n’a pas ce raccourci. Elle connaît une seule chose : l’URL http://127.0.0.1:8000/mcp. Elle ignore quel fournisseur délivre les jetons, quelles portées demander et quelle audience utiliser. Elle n’a pas non plus d’identifiant de client.

Sa première requête reçoit cette réponse, que vous avez vue dans Transport à distance :

HTTP/1.1 401 Unauthorized
www-authenticate: Bearer error="invalid_token", error_description="Authentication required", resource_metadata="http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp"

Il existe un deuxième risque. Un client peu prudent pourrait demander toutes les portées offertes par le fournisseur. Il pourrait aussi réutiliser un jeton destiné à un autre service. L’équipe du cours a rencontré le premier risque lors d’une exécution réelle, comme vous le verrez plus loin.

L’autorisation MCP utilise OAuth avec quelques documents standard. Les éléments portent des noms que vous avez vus dans le cours sur l’authentification, plus trois nouveaux.

Le serveur MCP est un serveur de ressources : il accepte les jetons et ne connecte jamais personne. Le fournisseur est le serveur d’autorisation : il connecte les personnes et délivre les jetons. Le serveur publie ses métadonnées de ressource protégée à une URL bien connue (RFC 9728). Ce document indique l’URL du serveur, le resource (ressource), et ses serveurs d’autorisation. Le fournisseur publie ses propres métadonnées de serveur d’autorisation (RFC 8414) : ses points de terminaison et les fonctionnalités prises en charge.

Un nouveau client peut s’inscrire par inscription dynamique des clients (RFC 7591) et reçoit un identifiant de client. La révision du 28 juillet 2026 préfère une autre méthode : un identifiant de client qui est l’URL d’un document de métadonnées. Elle conserve l’inscription dynamique, marquée comme obsolète, pour les fournisseurs qui ne prennent pas en charge cette méthode. Le fournisseur d’exercice et le client de la trousse SDK 2.3.0 utilisent l’inscription dynamique. Ensuite, le client exécute le flux de code d’autorisation avec PKCE (prononcé « pixie »). Il envoie aussi un paramètre resource (RFC 8707) contenant l’URL du serveur. Le fournisseur inscrit cette URL dans le jeton comme audience. Ainsi, un jeton pour ce serveur fonctionne seulement ici.

Une séquence entre quatre participants : la personne (Sam), l'hôte avec son client MCP (OAuthClientProvider de la trousse SDK), support-mcp (le serveur de ressources à :8000/mcp) et le fournisseur d'exercice (le serveur d'autorisation à :8400). 1. POST /mcp sans jeton. 2. 401 avec WWW-Authenticate : Bearer et resource_metadata pointant vers /.well-known/oauth-protected-resource/mcp. 3. GET de ce document. 4. 200 : resource :8000/mcp, authorization_servers [:8400], scopes_supported [knowledge:read, tickets:read]. 5. GET /.well-known/oauth-authorization-server auprès du fournisseur. 6. 200 : authorize, token, register, jwks_uri, S256. 7. POST /register avec une URI de redirection sur 127.0.0.1. 8. 201 : client_id client-…. 9. L'hôte ouvre /authorize pour la personne avec scope knowledge:read tickets:read, resource :8000/mcp, code_challenge et la méthode S256. 10. La personne se connecte (exercice : choisir une personne fictive). 11. 302 vers l'URI de redirection avec code et state. 12. POST /token avec le code, le code_verifier et le resource. 13. 200 : un jeton d'accès, Bearer, 600 s, audience :8000/mcp. 14. POST /mcp avec Authorization : Bearer et X-Support-Tenant : larkfield. Note au serveur : vérifier le jeton (signature avec le JWKS, émetteur, audience = sa propre URL, expiration), puis l'adhésion, la portée et la recherche. 15. 200 : get_ticket T-30002, isError false.
Le flux officiel, tel que le client de la trousse SDK l'a exécuté avec le fournisseur d'exercice. Le serveur vérifie seulement les jetons; le fournisseur connecte la personne.
Description textuelle du diagramme
  1. L’hôte envoie POST /mcp sans jeton. Le serveur répond 401, avec resource_metadata pointant vers /.well-known/oauth-protected-resource/mcp.
  2. L’hôte lit ce document : la ressource :8000/mcp, le serveur d’autorisation :8400 et scopes_supported (portées prises en charge) knowledge:read, tickets:read.
  3. L’hôte lit les métadonnées du fournisseur à /.well-known/oauth-authorization-server : les points de terminaison authorize, token et register, le JWKS et la méthode S256.
  4. L’hôte s’inscrit avec POST /register et une URI de redirection sur 127.0.0.1. Il reçoit un client_id (identifiant de client).
  5. L’hôte ouvre /authorize pour la personne, avec les portées, le resource et un défi de code PKCE. La personne se connecte; ici, elle choisit une personne fictive.
  6. Le fournisseur redirige vers l’URI de redirection de l’hôte avec un code. L’hôte envoie le code, le vérificateur de code et la ressource à POST /token. Il reçoit un jeton d’accès : Bearer, 600 secondes, audience :8000/mcp.
  7. L’hôte envoie POST /mcp avec le jeton et X-Support-Tenant: larkfield. Le serveur vérifie le jeton avec le JWKS du fournisseur : émetteur, audience égale à sa propre URL, expiration. Ensuite, il vérifie l’adhésion, la portée et la recherche, puis répond 200.

Un petit exemple : PKCE avec toutes les valeurs visibles

Section intitulée « Un petit exemple : PKCE avec toutes les valeurs visibles »

Le code de l’étape 6 passe par le navigateur, dans une URL de redirection. Quelqu’un pourrait le copier au passage. PKCE rend un code copié inutile. Voici l’exemple de la RFC 7636, la norme qui définit PKCE, avec toutes les valeurs.

PKCE : prouver que le code est à vous (l'exemple de la RFC 7636). Le vérificateur de code, conservé par l'hôte : dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk. Une flèche passe par SHA-256, puis base64url sans = à la fin, vers le défi de code envoyé au début : E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM. Étape 1 : /authorize avec code_challenge=E9Melhoa… et code_challenge_method=S256; le fournisseur conserve le défi avec le code. Étape 2 : POST /token avec le code et code_verifier=dBjftJeZ…; le fournisseur calcule l'empreinte du vérificateur et compare; la même valeur donne un jeton, et le code fonctionne une fois. Deux encadrés rouges : quelqu'un copie le code de la redirection, mais n'a pas de vérificateur : erreur invalid_grant, Invalid code verifier (vérificateur de code invalide). Le même code une deuxième fois : erreur invalid_grant, Unknown, used or expired code (code inconnu, utilisé ou expiré).
PKCE en deux étapes : l'hôte envoie d'abord une empreinte, puis le secret. Un code copié sans le secret ne donne aucun jeton.
Description textuelle du diagramme

L’hôte crée un vérificateur de code aléatoire et le conserve : dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk. Son empreinte SHA-256, écrite en base64url sans le = final, est le défi de code : E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM.

  1. L’hôte envoie le défi à /authorize, avec code_challenge_method=S256. Le fournisseur le conserve avec le code.
  2. L’hôte envoie le code et le vérificateur à POST /token. Le fournisseur calcule l’empreinte du vérificateur et compare. La même valeur donne un jeton, et le code fonctionne une fois.

Quelqu’un qui copie le code sans avoir le vérificateur reçoit {"error": "invalid_grant", "error_description": "Invalid code verifier."} (autorisation invalide, vérificateur de code invalide). Le même code envoyé une deuxième fois reçoit "Unknown, used or expired code." (code inconnu, utilisé ou expiré). Les deux réponses sont réelles.

Le calcul de l’empreinte fonctionne dans un seul sens. Tout le monde peut voir le défi, mais personne ne peut en déduire le vérificateur. C’est l’idée des chiffres du numéro de téléphone du cours sur l’authentification. Vous donnez les quatre derniers chiffres au début, et vous seul pouvez donner le numéro complet à la fin.

Vous exécutez chaque étape avec curl auprès du fournisseur d’exercice. Le fournisseur n’a pas de mots de passe : la page de connexion vous laisse choisir une personne fictive. Cela sert uniquement à apprendre.

  1. Copiez les fichiers de cette leçon et exécutez les tests :

    Fenêtre de terminal
    S=../nextia-learning-labs/C28/snapshots/end-of-m05
    cp "$S/tests/test_idp.py" "$S/tests/test_oauth.py" tests/
    cp "$S/scripts/oauth_login.py" scripts/
    cp "$S/docs/remote-design.md" docs/
    python -m pytest -q
    .................................................................... [100%]
    68 passed in 11.39s

    Dans PowerShell, copiez les quatre mêmes fichiers avec Copy-Item, comme dans les leçons précédentes.

  2. Lisez les métadonnées de ressource protégée du serveur :

    Fenêtre de terminal
    curl -s http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp
    {"resource":"http://127.0.0.1:8000/mcp","authorization_servers":["http://127.0.0.1:8400"],"scopes_supported":["knowledge:read","tickets:read"],"bearer_methods_supported":["header"]}

    resource est l’URL canonique du serveur : l’audience que ses jetons doivent indiquer.

  3. Lisez les métadonnées du fournisseur :

    Fenêtre de terminal
    curl -s http://127.0.0.1:8400/.well-known/oauth-authorization-server | python -m json.tool
    {
    "issuer": "http://127.0.0.1:8400",
    "authorization_endpoint": "http://127.0.0.1:8400/authorize",
    "token_endpoint": "http://127.0.0.1:8400/token",
    "registration_endpoint": "http://127.0.0.1:8400/register",
    "jwks_uri": "http://127.0.0.1:8400/jwks.json",
    "scopes_supported": [
    "knowledge:read",
    "tickets:read",
    "refunds:propose"
    ],
    "response_types_supported": [
    "code"
    ],
    "grant_types_supported": [
    "authorization_code"
    ],
    "code_challenge_methods_supported": [
    "S256"
    ],
    "token_endpoint_auth_methods_supported": [
    "none"
    ]
    }

    Remarquez refunds:propose : le fournisseur offre une portée d’écriture que le serveur n’annonce pas.

  4. Inscrivez un client et conservez son identifiant :

    Fenêtre de terminal
    CLIENT=$(curl -s -X POST http://127.0.0.1:8400/register -H "Content-Type: application/json" -d '{"client_name": "my-host", "redirect_uris": ["http://127.0.0.1:8765/callback"]}' | python -c 'import json,sys; print(json.load(sys.stdin)["client_id"])')
    echo $CLIENT
    client-e3fd4aab3604

    La réponse complète du fournisseur est {"client_name":"my-host","redirect_uris":["http://127.0.0.1:8765/callback"],"client_id":"client-e3fd4aab3604","client_id_issued_at":…,"token_endpoint_auth_method":"none"}. none (aucune) indique un client public : il n’a pas de secret, donc PKCE le protège. Votre identifiant sera différent.

  5. Créez une paire PKCE :

    Fenêtre de terminal
    read VERIFIER CHALLENGE < <(python -c "import secrets,hashlib,base64; v=secrets.token_urlsafe(48); print(v, base64.urlsafe_b64encode(hashlib.sha256(v.encode()).digest()).rstrip(b'=').decode())")
    echo ${#VERIFIER} ${#CHALLENGE}
    64 43

    Le vérificateur compte 64 caractères; le fournisseur en accepte de 43 à 128. Le défi en compte toujours 43.

  6. Construisez l’adresse de connexion et demandez un code en tant que Sam :

    Fenêtre de terminal
    AUTH="http://127.0.0.1:8400/authorize?response_type=code&client_id=$CLIENT&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback&scope=knowledge%3Aread%20tickets%3Aread&resource=http%3A%2F%2F127.0.0.1%3A8000%2Fmcp&code_challenge=$CHALLENGE&code_challenge_method=S256&state=xyz"
    curl -s -i "$AUTH&login_hint=usr-sam" | grep -i -E '^(HTTP|location)'
    HTTP/1.1 302 Found
    location: http://127.0.0.1:8765/callback?code=Lcr39eFHq1ki1M2RC9Uec02GBXCC0Xq_&state=xyz&iss=http%3A%2F%2F127.0.0.1%3A8400

    login_hint (indication de connexion) est un raccourci d’exercice qui saute la page de connexion. Ouvrez $AUTH sans ce paramètre dans un navigateur pour voir la page : « Practice sign-in. Made-up people only. Pick one : » (connexion d’exercice; personnes fictives seulement; choisissez-en une). Rien n’écoute sur le port 8765. Après votre choix, le navigateur affiche donc une erreur, avec le code dans sa barre d’adresse (non testé par le cours).

  7. Échangez le code contre un jeton. Copiez le code de la ligne location (emplacement) :

    Fenêtre de terminal
    CODE=Lcr39eFHq1ki1M2RC9Uec02GBXCC0Xq_
    curl -s -X POST http://127.0.0.1:8400/token -d "grant_type=authorization_code&code=$CODE&client_id=$CLIENT&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback&resource=http%3A%2F%2F127.0.0.1%3A8000%2Fmcp&code_verifier=$VERIFIER" > token.json
    python -c 'import json; t=json.load(open("token.json")); print(t["token_type"], t["expires_in"], t["scope"])'
    Bearer 600 knowledge:read tickets:read

    Un code reste valide pendant 60 secondes. Si cette étape affiche "Unknown, used or expired code.", répétez l’étape 6 et allez plus vite.

  8. Utilisez le jeton avec l’hôte :

    Fenêtre de terminal
    SIGNED=$(python -c 'import json; print(json.load(open("token.json"))["access_token"])')
    python -m host "Draft a reply to ticket T-30002" --http http://127.0.0.1:8000/mcp --token "$SIGNED" --tenant larkfield
    [host] discovered 2 tools: search_knowledge, get_ticket {"protocol": "2026-07-28", "server": "support-mcp"}
    [model] wants get_ticket {"arguments": {"ticket_id": "T-30002"}}
    ...
    Ticket T-30002 (open): Charged twice for order LK-182074.

    Décodez-le comme dans Transport à distance : aud (audience) vaut http://127.0.0.1:8000/mcp, selon votre paramètre resource. Le client_id est votre client inscrit.

  9. Supprimez token.json. Il contient un jeton valide pendant dix minutes.

idp/app.py contient environ 140 lignes de Starlette. Le point de terminaison de jeton montre les vérifications des étapes 6 et 7 dans l’ordre :

idp/app.py (token, the checks)
c = _codes.pop(form.get("code", ""), None) # a code works once
if c is None or c["expires"] < time.time():
return error("invalid_grant", "Unknown, used or expired code.")
if form.get("client_id") != c["client_id"] or form.get("redirect_uri") != c["redirect_uri"]:
return error("invalid_grant", "The code was issued to another client or redirect URI.")
verifier = form.get("code_verifier", "")
if not 43 <= len(verifier) <= 128:
return error("invalid_grant", "The code verifier must have 43 to 128 characters (RFC 7636).")
digest = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
if digest != c["challenge"]:
return error("invalid_grant", "Invalid code verifier.")

pop retire le code avant toute autre vérification. Un mauvais vérificateur consomme donc aussi le code. /authorize refuse un resource que le fournisseur ne connaît pas (invalid_target, cible invalide). Il refuse aussi toute méthode PKCE autre que S256. /register accepte seulement les URI de redirection sur 127.0.0.1 ou localhost. La signature utilise PyJWT et cryptography : aucune cryptographie n’est écrite à la main. C’est une copie simplifiée du fournisseur du cours sur l’authentification. Ne l’utilisez jamais pour de vrais comptes.

Un véritable hôte n’exécute pas neuf commandes curl. La trousse SDK Python de MCP possède un client OAuth, OAuthClientProvider, qui exécute chaque étape après une réponse 401. scripts/oauth_login.py se connecte avec ce client. Il démarre son propre fournisseur et son propre serveur sur des ports libres; n’arrêtez donc rien :

Fenêtre de terminal
python -m scripts.oauth_login
POST /mcp -> 401
GET /.well-known/oauth-protected-resource/mcp -> 200
GET /.well-known/oauth-authorization-server -> 200
POST /register -> 201
authorize: client client-e1177552f893, scope 'knowledge:read tickets:read', resource http://127.0.0.1:<server>/mcp, PKCE S256
callback: got an authorization code
POST /token -> 200
POST /mcp (with a token) -> 200
POST /mcp (with a token) -> 200
POST /mcp (with a token) -> 200
token: Bearer, expires in 600 s, scope 'knowledge:read tickets:read'
get_ticket T-30002 -> ok: Charged twice for order LK-182074

Ce sont les étapes du schéma de flux, dans le même ordre. Le script saute la page de connexion avec login_hint. Un véritable hôte ouvre la page dans le navigateur de la personne. Les trois POST /mcp avec un jeton sont server/discover, le tools/call et un tools/list envoyé automatiquement par la trousse SDK. Ce dernier vérifie le résultat selon le schéma de sortie de l’outil. Les lignes du journal du serveur et les lignes HTTP Request: (requête HTTP) de la trousse SDK vont vers stderr.

Une vraie surprise : la trousse SDK a demandé toutes les portées

Section intitulée « Une vraie surprise : la trousse SDK a demandé toutes les portées »

La première exécution de ce script, avant la correction que vous voyez maintenant, a demandé ceci au fournisseur :

&scope=knowledge%3Aread+tickets%3Aread+refunds%3Apropose

Le client du script indiquait scope="knowledge:read tickets:read". La trousse SDK a remplacé cette valeur par les trois portées, y compris celle d’écriture. Un hôte qui ne fait que lire aurait détenu un jeton permettant de proposer des remboursements.

Quelles portées le client OAuth de la trousse SDK demande-t-il? (SDK 2.3.0). Il prend la première liste trouvée, dans cet ordre, et remplace la portée du client. 1. scope dans la réponse 401 du serveur, dans WWW-Authenticate (aucune ici). 2. scopes_supported dans les métadonnées de ressource protégée du serveur à /.well-known/oauth-protected-resource/mcp. 3. scopes_supported du fournisseur, le recours par défaut de la trousse SDK, à /.well-known/oauth-authorization-server. Avant la correction, en rouge : le serveur n'annonçait aucune portée (aucun required_scopes), donc la trousse SDK utilisait 3 : scope=knowledge:read tickets:read refunds:propose. Un jeton qui permet de proposer des remboursements, pour une application qui ne fait que lire. Après la correction, en vert, le projet actuel : required_scopes = knowledge:read, tickets:read, donc les métadonnées de ressource indiquent scopes_supported [knowledge:read, tickets:read]; scope=knowledge:read tickets:read; la portée d'écriture est accordée séparément.
La trousse SDK 2.3.0 choisit d'abord ses portées à partir du serveur. Un serveur qui n'annonce rien laisse le client demander tout ce que le fournisseur offre.
Description textuelle du diagramme

La trousse SDK 2.3.0 prend la première liste de portées trouvée, dans cet ordre, et remplace celle du client :

  1. un scope (portée) dans l’en-tête WWW-Authenticate de la réponse 401 du serveur (aucun ici);
  2. scopes_supported dans les métadonnées de ressource protégée du serveur;
  3. scopes_supported dans les métadonnées du fournisseur, le recours par défaut de la trousse SDK.

Avant la correction, le serveur n’annonçait aucune portée. La trousse SDK utilisait donc la troisième liste : knowledge:read tickets:read refunds:propose. Après la correction, required_scopes (portées requises) contient les deux portées de lecture. Les métadonnées de ressource annoncent seulement celles-ci, et la trousse SDK demande knowledge:read tickets:read. La portée d’écriture est accordée séparément.

Les deux premières étapes suivent la sélection des portées de la spécification MCP. La troisième est un recours par défaut dans le code de la trousse SDK (get_client_metadata_scopes). La correction se fait sur le serveur, car il connaît ses besoins :

support_mcp/http.py
READ_SCOPES = ("knowledge:read", "tickets:read")
...
required_scopes=list(READ_SCOPES),

required_scopes fait deux choses. Les métadonnées annoncent exactement ces portées, donc un client n’en demande pas davantage. Et la trousse SDK refuse un jeton qui ne les possède pas avec HTTP 403 insufficient_scope (portée insuffisante), avant MCP. Demander le minimum nécessaire est le moindre privilège. Limites des identifiants ajoute la portée d’écriture comme autorisation distincte.

Le paramètre resource explique pourquoi le champ aud du jeton contient l’URL du serveur. La vérification du serveur refuse toute autre valeur. Voici un vrai jeton que le fournisseur a créé pour une autre API, ticket-api, puis envoyé à ce serveur :

HTTP/1.1 401 Unauthorized
www-authenticate: Bearer error="invalid_token", error_description="Authentication required", resource_metadata="http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp"

Le journal du serveur indique la raison : "event": "token_refused", "reason": "wrong_audience" (jeton refusé, mauvaise audience). La règle fonctionne aussi dans l’autre sens. Ce serveur ne transmet jamais le jeton d’une personne à un autre service, qui doit aussi le refuser. Cette règle porte un nom : aucune transmission de jeton (token passthrough). Limites des identifiants la teste.

Utilisez-le pour tout client exécuté par une personne que vous ne contrôlez pas : un assistant de bureau, un éditeur de code, l’application d’un partenaire. Ces clients peuvent trouver le fournisseur, s’inscrire et connecter la personne sans configuration de votre part. Utilisez une méthode plus simple seulement pour les tests et les scripts sur votre ordinateur, comme python -m idp token dans ce cours. Indiquez-le clairement.

Les coûts. Le fournisseur est un nouveau service à exploiter. S’il tombe en panne, personne ne peut se connecter. Les URI de redirection, l’audience et les portées sont des paramètres de sécurité : une erreur constitue un vrai bogue. L’inscription ouverte permet à n’importe qui de créer un client. Un vrai fournisseur la limite donc. Les jetons expirent après quelques minutes. Le fournisseur d’exercice n’émet aucun jeton de renouvellement, donc la personne doit se reconnecter.

Ce que le cours n’a pas testé. Un vrai fournisseur d’identité comme Keycloak ou Microsoft Entra ID, HTTPS, les jetons de renouvellement et tout assistant de bureau ou éditeur de code comme client. Un vrai fournisseur peut fonctionner autrement. Certains écrivent typ: JWT plutôt que at+jwt, comme le montre le cours Authentification, autorisations et applications multilocataires. D’autres ne prennent pas en charge l’inscription dynamique.

Erreur courante

invalid_target : ressource inconnue

Symptôme : /authorize répond {"error":"invalid_target","error_description":"Unknown resource: 'https://api.example.com/tickets'."} (ressource inconnue).

Cause : le paramètre resource désigne un serveur pour lequel le fournisseur n’émet pas de jetons. La liste du fournisseur est IDP_RESOURCES. Par défaut, elle contient http://127.0.0.1:8000/mcp et http://localhost:8000/mcp.

Solution : envoyez l’URL exacte du serveur, tirée de ses métadonnées de ressource protégée. Si vous avez changé le port du serveur, ajoutez son URL à IDP_RESOURCES dans le terminal du fournisseur. Redémarrez ensuite le fournisseur.

Erreur courante

invalid_request : PKCE avec S256

Symptôme : /authorize répond {"error":"invalid_request","error_description":"This provider needs response_type=code and PKCE with S256."} (ce fournisseur exige response_type=code et PKCE avec S256).

Cause : la requête utilise code_challenge_method=plain, ou aucun défi. La méthode plain envoie le secret lui-même au départ. Elle ne protège donc rien.

Solution : envoyez le défi SHA-256 avec code_challenge_method=S256, comme à l’étape 5.

Réinitialisation. Si votre projet ne fonctionne plus, copiez l’instantané complet end-of-m05, comme dans La place de MCP. Supprimez .idp/ et exécutez python -m idp init pour créer une nouvelle clé d’exercice.

Vérifiez votre compréhension

Un nouveau client connaît seulement l'URL du serveur. Nommez les deux documents de métadonnées qu'il lit et un fait qu'il apprend dans chacun.

Afficher la réponse

Les métadonnées de ressource protégée du serveur, à /.well-known/oauth-protected-resource/mcp : l’URL de la ressource (l’audience), le serveur d’autorisation et les portées à demander. Les métadonnées du serveur d’autorisation du fournisseur, à /.well-known/oauth-authorization-server : les points de terminaison d’autorisation, de jeton et d’inscription, les JWKS et l’obligation d’utiliser S256 avec PKCE. L’en-tête resource_metadata de la réponse 401 pointe vers le premier document.

Vérifiez votre compréhension

Prédisez : quelqu'un copie le code de l'URL de redirection et l'envoie à /token avec son propre vérificateur. Que se passe-t-il? L'hôte légitime peut-il encore utiliser le code?

Afficher la réponse

Le fournisseur répond invalid_grant, « Invalid code verifier. » (vérificateur de code invalide) : le SHA-256 de son vérificateur ne correspond pas au défi. Le fournisseur supprime le code avant de vérifier le vérificateur. L’hôte légitime reçoit donc « Unknown, used or expired code. » (code inconnu, utilisé ou expiré) et doit recommencer. Personne n’obtient de jeton avec un code copié.

Vérifiez votre compréhension

Vérification pratique : exécutez python -m scripts.oauth_login. Quelle portée la trousse SDK a-t-elle demandée? Qu'est-ce qui lui fait demander exactement cela?

Afficher la réponse

scope 'knowledge:read tickets:read' (portées knowledge:read et tickets:read). Le serveur définit required_scopes avec les deux portées de lecture. Ses métadonnées de ressource protégée annoncent donc seulement celles-ci. La trousse SDK 2.3.0 utilise scopes_supported des métadonnées de la ressource avant la liste du fournisseur. Sans ce paramètre, elle utilisait la liste du fournisseur et demandait aussi refunds:propose.

Exercice : concevoir et tester l’accès à distance

Section intitulée « Exercice : concevoir et tester l’accès à distance »

Cet exercice termine le module. Vous lisez d’abord un exemple détaillé, puis vous modifiez vous-même une condition.

Ouvrez docs/remote-design.md. Ce document présente la conception du déploiement à distance de support-mcp par Amira. Il contient le tableau de Transport à distance, le flux de requêtes de cette leçon en cinq étapes et quatre décisions :

  • L’organisation vient de la connexion, jamais du modèle.
  • Le rôle vient de la table des adhésions du serveur, jamais du jeton.
  • Le serveur ne transmet jamais le jeton de l’utilisateur.
  • La production exige HTTPS, un vrai fournisseur d’identité, des jetons valides quelques minutes, des journaux sans jetons et une limite de requêtes par appelant.

Sa preuve est python -m scripts.attempts, avec 48 tentatives par des identités synthétiques. Le serveur en autorise 15 et en refuse 33, chacune avec le nom de sa vérification. Lisez la conception en parallèle avec le tableau. Chaque décision de conception a au moins une ligne de refus comme preuve.

Tâche autonome : un partenaire limité à la recherche

Section intitulée « Tâche autonome : un partenaire limité à la recherche »

L’application partenaire d’Omar a un seul besoin : chercher dans les politiques de Larkfield. Elle ne doit jamais lire un billet. Modifiez une condition, les portées, et déterminez les conséquences :

  1. Créez un jeton avec seulement la portée de recherche. Prédisez la réponse du serveur à une recherche : python -m idp token --user usr-omar --scope knowledge:read.
  2. Essayez-le avec l’hôte et une question sur une politique. Expliquez la réponse à partir du code de http.py.
  3. Déterminez comment modifier le serveur pour que le partenaire puisse chercher, mais pas lire les billets. Modifiez votre projet et testez de nouveau les deux requêtes.
  4. Exécutez les tests. Expliquez chaque échec : un bogue ou un test qui imposait l’ancienne conception?
  5. Ajoutez une section « Accès du partenaire » à docs/remote-design.md : les portées, les preuves et les questions encore ouvertes.
Afficher la solution détaillée

1 et 2. Dans son état actuel, le projet refuse toutes les requêtes de ce jeton avant MCP. L’hôte affiche une longue trace d’erreur qui se termine par MCPError: Server returned an error response (le serveur a renvoyé une réponse d’erreur). Avec curl, la réponse est plus claire :

HTTP/1.1 403 Forbidden
www-authenticate: Bearer error="insufficient_scope", error_description="Required scope: tickets:read", resource_metadata="http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp"

required_scopes contient les deux portées de lecture. La couche HTTP de la trousse SDK exige donc les deux pour chaque requête, même une recherche.

3. Chaque outil vérifie déjà sa propre portée : search_knowledge exige knowledge:read, et get_ticket exige tickets:read. La couche HTTP doit donc seulement exiger la portée nécessaire à toutes les requêtes. Dans support_mcp/http.py :

READ_SCOPES = ("knowledge:read",)

Redémarrez le serveur. Les métadonnées annoncent maintenant une seule portée :

{"resource":"http://127.0.0.1:8000/mcp","authorization_servers":["http://127.0.0.1:8400"],"scopes_supported":["knowledge:read"],"bearer_methods_supported":["header"]}

La recherche du partenaire fonctionne. La vérification propre à l’outil refuse l’accès au billet :

[server] result: 1078 characters {"ms": 196.8, "clipped": false}
...
From "Returns policy" (policy://larkfield/returns-policy): … ## Return window You can return an unused item …
[server] protocol error -32003: insufficient_scope: this needs the scope tickets:read {"code": -32003}
...
I could not use get_ticket: insufficient_scope: this needs the scope tickets:read

4. 3 failed, 65 passed (3 échecs, 65 réussites). Les trois échecs sont test_a_token_without_the_read_scopes_is_refused_before_mcp, test_the_resource_metadata_advertises_only_the_read_scopes et test_the_sdk_client_signs_in_and_asks_only_for_the_advertised_scopes. Ce ne sont pas des bogues : ces tests imposaient volontairement l’ancienne conception. Adaptez-les à la nouvelle conception. Ajoutez un test qui vérifie qu’un jeton knowledge:read reçoit −32003 pour get_ticket. Modifier un test de sécurité constitue une décision : consignez-la.

5. Une bonne section décrit le compromis. Le client de la trousse SDK demande maintenant seulement knowledge:read. L’hôte du service de soutien, qui a besoin des billets, doit donc demander lui-même tickets:read. Sinon, la réponse 401 doit nommer la portée. Le refus d’une portée manquante à la couche HTTP donnait une réponse 403 claire. Maintenant, une lecture de billet sans cette portée donne −32003 dans MCP. Les deux sont des refus du serveur. L’équipe du cours a exécuté les étapes 1 à 4 exactement ainsi; vos temps diffèrent.

Vérification finale : refuser sur le serveur, pas dans l’hôte

Section intitulée « Vérification finale : refuser sur le serveur, pas dans l’hôte »

Montrez que le serveur lui-même refuse trois types d’accès, sans aide de l’hôte. Avec le fournisseur et le serveur en marche, envoyez chaque requête avec curl ou l’hôte du cours :

  1. aucun jeton;
  2. un jeton pour une autre API : python -m idp token --user usr-sam --audience ticket-api;
  3. les données d’une autre organisation : le jeton valide de Camille avec X-Support-Tenant: larkfield et le billet T-40003, puis le jeton valide d’Ines avec X-Support-Tenant: larkfield.

Pour chaque cas, notez le statut ou l’erreur, ainsi que la ligne du journal du serveur ou le test qui le prouve.

Afficher la solution détaillée
  1. Aucun jeton : HTTP/1.1 401 Unauthorized (non autorisé), www-authenticate: Bearer error="invalid_token", error_description="Authentication required", resource_metadata="…" (authentification requise). Aucune requête MCP n’a atteint un outil. Test : test_no_token_gets_401_and_where_to_sign_in.
  2. Mauvaise audience : la même réponse 401, volontairement : la réponse ne révèle rien à un inconnu. Le journal du serveur indique "event": "token_refused", "reason": "wrong_audience" (jeton refusé, mauvaise audience). Test : test_bad_tokens_get_401[wrong_audience].
  3. Autre organisation : Camille, chez Larkfield, demande T-40003 et reçoit l’erreur d’outil not_found: there is no ticket T-40003 in this organization (aucun billet T-40003 dans cette organisation). Avec X-Support-Tenant: bramble, Camille obtient le billet. Ines, chez Larkfield, reçoit −32003 forbidden: you have no access to this organization (vous n’avez pas accès à cette organisation). Tests : test_a_cross_tenant_id_is_not_found et test_another_organization_is_refused_on_the_server.

Pourquoi « pas dans l’hôte »? curl n’a ni liste d’autorisation, ni confirmation, ni modèle. Chaque refus ci-dessus vient uniquement du serveur. python -m pytest -q tests/test_http.py affiche 14 passed (14 réussites) et les répète tous.

Démontré signifie : les trois accès sont refusés, chacun avec sa preuve, et vous expliquez pourquoi un paramètre de l’hôte ne suffit pas. Partiellement démontré : les refus se produisent, mais il manque une preuve ou une explication pour l’un d’eux. Pas encore démontré : une des trois requêtes réussit.

Récapitulatif

  • Streamable HTTP offre les mêmes outils à une seule URL. Dans la révision du 28 juillet 2026, chaque requête est indépendante, sans session. Pour les exercices, un serveur distant se lie à 127.0.0.1. Au-delà de votre ordinateur, il exige HTTPS.
  • Chaque requête contient un jeton d’accès. Son audience est l’URL du serveur lui-même. Le serveur refuse donc un jeton destiné à une autre API.
  • L’authentification prouve qui; l’autorisation décide quoi, sur le serveur, pour chaque requête : jeton, adhésion, portée, rôle, recherche limitée à l’organisation. L’organisation vient de la connexion; le rôle vient de la table du serveur.
  • Un nouveau client obtient un jeton par la méthode officielle. Il suit la réponse 401 vers les métadonnées de ressource protégée et celles du fournisseur. Il s’inscrit, puis exécute le flux de code avec PKCE et le paramètre resource.
  • Annoncez seulement les portées dont le client a besoin. Sinon, la trousse SDK 2.3.0 demande toutes les portées offertes par le fournisseur.

Votre projet contient maintenant 68 tests, le fournisseur d’exercice et docs/remote-design.md. Dans le module 6, l’application d’IA rencontre du texte non fiable dans les billets et les résultats d’outils. Le serveur reçoit aussi sa première opération d’écriture.

Leçon suivante : Entrées et sorties non fiables