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é.
Leçon 16 sur 22 · MCP : connecter les applications d'IA aux outils et aux donnéesIntégration d'OAuth
1. Comprendre le problème d'intégration
2. Concevoir des capacités de serveur utiles
3. Créer et examiner un serveur local
4. Connecter une application d'IA
5. Accès à distance et autorisation
6. Protéger les outils et le contrôle de l'utilisateur
7. Exploiter et maintenir l'intégration
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 main
Ce que vous devez savoir
- La réponse 401 et son lien
resource_metadata, présentés dans Transport à distance. - Comment le serveur transforme un jeton en appelant, présenté dans Identité et autorisations.
- Le flux de code d’autorisation, PKCE et la vérification de l’audience, présentés dans OAuth et OIDC et Ce que signifie un jeton.
Votre projet
~/projects/support-mcpaprès Identité et autorisations :python -m pytest -qaffiche63 passed(63 tests réussis).- Le terminal 1 exécute
python -m idp, le terminal 2 exécutepython -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.
Le problème : un nouveau client ne sait rien
Section intitulée « Le problème : un nouveau client ne sait rien »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 Unauthorizedwww-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’idée : le flux d’autorisation MCP
Section intitulée « L’idée : le flux d’autorisation MCP »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.
Description textuelle du diagramme
- L’hôte envoie
POST /mcpsans jeton. Le serveur répond 401, avecresource_metadatapointant vers/.well-known/oauth-protected-resource/mcp. - L’hôte lit ce document : la ressource
:8000/mcp, le serveur d’autorisation:8400etscopes_supported(portées prises en charge)knowledge:read,tickets:read. - 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. - L’hôte s’inscrit avec
POST /registeret une URI de redirection sur127.0.0.1. Il reçoit unclient_id(identifiant de client). - L’hôte ouvre
/authorizepour la personne, avec les portées, leresourceet un défi de code PKCE. La personne se connecte; ici, elle choisit une personne fictive. - 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. - L’hôte envoie
POST /mcpavec le jeton etX-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.
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.
- L’hôte envoie le défi à
/authorize, aveccode_challenge_method=S256. Le fournisseur le conserve avec le code. - 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.
Larkfield : le flux à la main
Section intitulée « Larkfield : le flux à la main »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.
-
Copiez les fichiers de cette leçon et exécutez les tests :
Fenêtre de terminal S=../nextia-learning-labs/C28/snapshots/end-of-m05cp "$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.39sDans PowerShell, copiez les quatre mêmes fichiers avec
Copy-Item, comme dans les leçons précédentes. -
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"]}resourceest l’URL canonique du serveur : l’audience que ses jetons doivent indiquer. -
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. -
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 $CLIENTclient-e3fd4aab3604La 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. -
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 43Le vérificateur compte 64 caractères; le fournisseur en accepte de 43 à 128. Le défi en compte toujours 43.
-
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 Foundlocation: http://127.0.0.1:8765/callback?code=Lcr39eFHq1ki1M2RC9Uec02GBXCC0Xq_&state=xyz&iss=http%3A%2F%2F127.0.0.1%3A8400login_hint(indication de connexion) est un raccourci d’exercice qui saute la page de connexion. Ouvrez$AUTHsans 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). -
É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.jsonpython -c 'import json; t=json.load(open("token.json")); print(t["token_type"], t["expires_in"], t["scope"])'Bearer 600 knowledge:read tickets:readUn 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. -
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) vauthttp://127.0.0.1:8000/mcp, selon votre paramètreresource. Leclient_idest votre client inscrit. -
Supprimez
token.json. Il contient un jeton valide pendant dix minutes.
Lisez le fournisseur
Section intitulée « Lisez le fournisseur »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 :
c = _codes.pop(form.get("code", ""), None) # a code works onceif 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.
Le client de la trousse SDK fait tout
Section intitulée « Le client de la trousse SDK fait tout »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 :
python -m scripts.oauth_loginPOST /mcp -> 401GET /.well-known/oauth-protected-resource/mcp -> 200GET /.well-known/oauth-authorization-server -> 200POST /register -> 201authorize: client client-e1177552f893, scope 'knowledge:read tickets:read', resource http://127.0.0.1:<server>/mcp, PKCE S256callback: got an authorization codePOST /token -> 200POST /mcp (with a token) -> 200POST /mcp (with a token) -> 200POST /mcp (with a token) -> 200token: Bearer, expires in 600 s, scope 'knowledge:read tickets:read'get_ticket T-30002 -> ok: Charged twice for order LK-182074Ce 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%3AproposeLe 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.
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 :
- un
scope(portée) dans l’en-têteWWW-Authenticatede la réponse 401 du serveur (aucun ici); scopes_supporteddans les métadonnées de ressource protégée du serveur;scopes_supporteddans 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 :
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.
L’audience : un jeton pour un seul serveur
Section intitulée « L’audience : un jeton pour un seul serveur »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 Unauthorizedwww-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.
Quand utiliser ce flux et quels sont ses coûts
Section intitulée « Quand utiliser ce flux et quels sont ses coûts »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.
Erreurs courantes
Section intitulée « Erreurs courantes »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érification des connaissances
Section intitulée « Vérification des connaissances »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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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é.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
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.
Exercice guidé : l’exemple détaillé
Section intitulée « Exercice guidé : l’exemple détaillé »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 :
- 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. - Essayez-le avec l’hôte et une question sur une politique. Expliquez la réponse à partir du code de
http.py. - 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.
- Exécutez les tests. Expliquez chaque échec : un bogue ou un test qui imposait l’ancienne conception?
- 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 Forbiddenwww-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:read4. 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 :
- aucun jeton;
- un jeton pour une autre API :
python -m idp token --user usr-sam --audience ticket-api; - les données d’une autre organisation : le jeton valide de Camille avec
X-Support-Tenant: larkfieldet le billet T-40003, puis le jeton valide d’Ines avecX-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
- 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. - 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]. - 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). AvecX-Support-Tenant: bramble, Camille obtient le billet. Ines, chez Larkfield, reçoit −32003forbidden: you have no access to this organization(vous n’avez pas accès à cette organisation). Tests :test_a_cross_tenant_id_is_not_foundettest_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 du module
Section intitulée « Récapitulatif du module »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