Votre agent doit lire le calendrier d'un client, envoyer un message depuis son compte, ou créer un ticket sous son nom. La version rapide consiste à détenir un compte de service avec un accès large et à agir par son intermédiaire. Chaque action apparaît comme « l'intégration », personne ne peut dire quel utilisateur a déclenché quoi, et un seul identifiant compromis expose tous les comptes que vous touchez.
La version correcte est l'autorisation déléguée : l'utilisateur accorde à votre agent un jeton limité et révocable, l'agent agit en tant que cet utilisateur, et la piste d'audit les nomme. C'est pour cela qu'OAuth 2.0 a été conçu. Ce qui le rend délicat pour les agents, c'est qu'OAuth suppose la présence d'un navigateur et d'une personne pour cliquer sur « Autoriser », alors que les agents fonctionnent en arrière-plan à 3h du matin.
Ce guide couvre quel flux OAuth convient à un agent, comment définir la portée et stocker les jetons, que faire concernant le rafraîchissement et la révocation, et comment tester le chemin complet sans compte réel. Si vous hésitez encore entre l'authentification par clé et l'authentification déléguée, notre comparaison des clés API et d'OAuth est le point de départ.
Apidog aide les équipes avec la partie qu'elles sous-estiment : exercer chaque branche du flux, y compris l'expiration et la révocation, avant qu'un agent ne les rencontre en production.
Compte de service ou accès délégué
Choisissez délibérément, car les deux modèles échouent différemment.
Un compte de service est l'identité propre de votre agent, avec ses propres permissions. Il convient au travail que l'agent effectue en votre nom : lire votre propre base de données, appeler vos propres services internes, exécuter des tâches planifiées sur votre infrastructure. Limitez sa portée de manière stricte, comme dans notre article sur les clés API à moindre privilège pour les agents, et faites-le pivoter.
L'accès délégué est l'agent agissant en tant qu'utilisateur spécifique, avec les permissions de cet utilisateur et pas plus. Il est requis chaque fois que les données appartiennent à quelqu'un d'autre. Trois propriétés en valent l'effort supplémentaire : l'utilisateur peut voir ce qui a été accordé, l'utilisateur peut le révoquer, et chaque action porte son identité dans le journal.
Le mode d'échec à éviter est un compte de service avec un accès à l'échelle de l'organisation utilisé pour agir « en tant que » utilisateurs. Cela fonctionne, et cela signifie qu'un seul identifiant divulgué expose tout le monde, sans révocation par utilisateur et sans piste d'audit honnête.
Quel flux convient à un agent
OAuth 2.0 définit plusieurs types d'octroi, et seuls quelques-uns sont pertinents ici. La spécification OAuth 2.0 contient l'ensemble complet ; voici ceux que vous utiliserez.
Code d'autorisation avec PKCE. Le flux standard pour agir en tant qu'utilisateur. L'utilisateur est redirigé vers le fournisseur, approuve les scopes, et votre service échange le code contre des jetons. PKCE protège l'échange et est désormais la recommandation par défaut pour tous les types de clients, selon les meilleures pratiques de sécurité actuelles d'OAuth 2.0. Notre présentation du flux d'octroi de code d'autorisation couvre les mécanismes étape par étape.
Le point spécifique à l'agent : ce flux s'exécute une seule fois, en présence de l'humain, au moment de la connexion. L'agent ne l'exécute jamais. Il utilise le jeton de rafraîchissement que le flux a produit. Séparez ces deux moments dans votre conception et la majeure partie de la difficulté disparaît.
Identifiants client. De machine à machine, aucun utilisateur impliqué. Correct pour les comptes de service et incorrect pour agir en tant qu'utilisateur, car il n'y a pas d'utilisateur pour consentir.
Octroi d'autorisation d'appareil. Pour les agents sur des machines sans navigateur. L'utilisateur reçoit un code et approuve sur son téléphone. Utile pour les agents CLI et les environnements sans interface graphique.
Échange de jetons. La RFC 8693 permet à un service d'échanger un jeton contre un plus restrictif. C'est ainsi que vous donnez à un sous-agent un jeton limité à un scope pour une tâche, dérivé de l'octroi plus large de l'utilisateur, sans lui remettre l'original. Si vous utilisez des systèmes multi-agents, c'est le mécanisme qui rend les identifiants par agent pratiques, et il correspond aux règles de délimitation de notre article sur le transfert multi-agents.
Définissez des scopes étroits, et par agent
Les scopes sont là où l'accès délégué prend tout son sens, et là où la plupart des implémentations deviennent paresseuses en demandant tout ce dont l'application pourrait avoir besoin.
Demandez uniquement ce que cet agent fait. Un agent de planification a besoin d'écrire dans le calendrier et rien d'autre. Pas de courrier, pas de contacts, pas de fichiers. Les utilisateurs lisent l'écran de consentement, et une longue liste est à la fois un problème de confiance et un problème de zone d'impact. Notre explication sur les scopes OAuth 2 couvre la façon dont les fournisseurs les modélisent.
Demandez de manière incrémentale. Demandez le minimum au moment de la connexion, puis demandez plus lorsque l'utilisateur demande une fonctionnalité qui en a besoin. Un consentement lié à une demande concrète est plus facile à accorder et plus facile à justifier.
Donnez à chaque agent son propre jeton. Si un agent de recherche et un agent de facturation agissent tous deux pour le même utilisateur, dérivez deux jetons avec des scopes différents plutôt que d'en partager un. Ainsi, un agent de recherche compromis ne peut pas émettre de remboursements, et le journal vous indique quel agent a agi.
Préférez les scopes de lecture par défaut et exigez une escalade explicite pour les écritures. Combinez cela avec une porte d'approbation sur les appels destructeurs, comme dans notre article sur les garde-fous des agents IA, afin qu'un jeton pouvant écrire ne soit pas la seule chose qui se dresse entre l'agent et une erreur.
Stocker, rafraîchir et révoquer
Les jetons sont des identifiants, traitez-les comme tels.
Stockage. Chiffrez les jetons de rafraîchissement au repos, avec une clé par utilisateur. Ne les écrivez jamais dans les journaux, ne les mettez jamais dans les invites et ne laissez jamais un modèle en voir un. Un jeton en contexte est un jeton dans votre magasin de traces, les journaux de votre fournisseur, et éventuellement un résumé. Notre article sur le traçage des appels d'outils d'agent couvre la rédaction à la limite plutôt qu'au moment de la lecture.
Rafraîchissement. Les jetons d'accès sont de courte durée par conception. L'agent ne devrait jamais gérer cela lui-même ; un gestionnaire de jetons devant le client HTTP rafraîchit le jeton lorsque l'expiration est proche et relance l'appel une fois sur un 401.
class TokenManager:
def __init__(self, store, provider):
self.store, self.provider = store, provider
def access_token(self, user_id, agent_scope):
rec = self.store.get(user_id, agent_scope)
if rec.expires_in() > 60:
return rec.access_token
fresh = self.provider.refresh(rec.refresh_token, scope=agent_scope)
self.store.save(user_id, agent_scope, fresh) # rotation: store the new refresh token
return fresh.access_token
Deux détails importants. Les fournisseurs rotatent de plus en plus les jetons de rafraîchissement, en émettant un nouveau à chaque rafraîchissement et en invalidant l'ancien, alors persistez le nouveau immédiatement ou vous bloquerez l'utilisateur. Et sérialisez les rafraîchissements par utilisateur, car deux rafraîchissements concurrents avec un fournisseur rotatif entreront en concurrence et l'un perdra.
Révocation. Les utilisateurs révoquent l'accès, les jetons expirent, les administrateurs suppriment les comptes. L'agent doit traiter les 401 et 403 comme définitifs plutôt que comme réessayables. Réessayer un échec d'authentification n'aide jamais et peut déclencher des protections contre les abus. Retournez un message clair nommant l'utilisateur et le scope afin qu'un humain puisse agir, en suivant les modèles d'erreur de notre article sur la conception des erreurs API pour les agents IA.
Le problème du consentement
La partie délicate des agents et d'OAuth : le consentement nécessite un humain, et les agents fonctionnent sans surveillance.
Séparez le temps de connexion du temps d'exécution et cela devient gérable. Au moment de la connexion, une personne autorise une fois, avec un navigateur, et vous stockez un jeton de rafraîchissement. Au moment de l'exécution, l'agent utilise cet octroi sans intervention humaine. Cela fonctionne pour les agents planifiés et en arrière-plan, ce qui est la plupart d'entre eux.
Deux limites à prévoir. Les octrois expirent, parfois après des mois d'inactivité, parfois par politique. Détectez un octroi expiré, arrêtez l'exécution et informez l'utilisateur, plutôt que d'échouer silencieusement chaque nuit. Et le consentement a un plafond de scope : un agent qui a besoin d'un scope que l'utilisateur n'a jamais accordé doit demander plutôt que d'escalader de lui-même.
Pour toute action à enjeux élevés, ajoutez une deuxième porte au moment de l'action. Le jeton prouve que l'agent peut agir ; une porte d'approbation décide s'il doit le faire. Ce sont des questions différentes et les deux méritent une réponse.
Testez le flux avant qu'un agent ne le rencontre
Les chemins de code d'authentification sont la partie la moins testée de la plupart des intégrations, car les exercer manuellement signifie cliquer à travers les écrans d'un fournisseur.
Développez ces cinq cas :
- Chemin normal. Un jeton d'accès valide, un appel réussi. La référence.
- Jeton d'accès expiré. Le fournisseur renvoie
401, le gestionnaire rafraîchit, l'appel est relancé une fois et réussit. C'est le chemin réel le plus courant et souvent le moins testé. - Jeton de rafraîchissement révoqué. Le rafraîchissement renvoie
invalid_grant. L'agent doit s'arrêter et signaler, pas boucler. - Scope insuffisant. Un
403avec une erreur de scope. L'agent ne doit pas réessayer, et doit indiquer quel scope est manquant. - Rafraîchissement concurrent. Deux appels pour le même utilisateur en même temps. Un seul rafraîchissement devrait avoir lieu.
Exécutez-les contre des mocks. Dans Apidog, vous pouvez définir le point de terminaison de jeton et les points de terminaison protégés, puis simuler chaque réponse, y compris les corps d'erreur, de sorte que toute la matrice s'exécute sans toucher à un vrai fournisseur. Notre article sur l'exécution d'agents contre des mocks plutôt qu'en production couvre l'habitude plus large, et notre guide de test d'API OAuth 2 couvre les détails au niveau de la requête.
Trois intégrations et ce dont elles ont besoin
Un assistant calendrier. Lit les disponibilités et réserve des réunions pour un utilisateur. Accès délégué, deux scopes, consentement au moment de la connexion dans un navigateur, exécutions en arrière-plan par la suite. L'échec intéressant est la révocation : l'utilisateur déconnecte l'intégration et l'exécution nocturne doit le remarquer et s'arrêter plutôt que de retenter un octroi mort pendant une semaine.
Un agent de support dans une boîte de réception partagée. Agit sur des tickets appartenant à une équipe. Ici, la question de l'identité devient plus précise. Agir en tant que compte partagé de l'équipe est défendable, puisque la ressource appartient réellement à l'équipe, mais chaque réponse apparaît alors identique dans le journal d'audit. Mieux vaut une identité de bot avec ses propres scopes et un enregistrement de l'humain qui a déclenché l'exécution, ce qui maintient l'attribution intacte sans prétendre que l'agent est une personne.
Un agent d'opérations interne. Redémarre les services et lit les tableaux de bord de votre propre infrastructure. Pas de données utilisateur, pas de délégation. Un compte de service avec des scopes étroits est la bonne réponse, et le travail est consacré à la rotation et à la zone d'impact plutôt qu'au consentement.
La ligne de démarcation est la propriété. Si les données appartiennent à quelqu'un qui pourrait raisonnablement vouloir révoquer votre accès, utilisez l'authentification déléguée. Si elles vous appartiennent, utilisez un compte de service et concentrez vos efforts sur la définition de la portée.
Gardez l'humain dans l'attribution
L'authentification déléguée répond à la question « au nom de qui ». Elle ne répond pas à la question « à la demande de qui », et pour le travail d'agent, vous voulez les deux. Un jeton prouve que l'agent peut agir en tant qu'utilisateur ; il n'enregistre pas la personne qui a demandé l'exécution.
Gardez cette deuxième identité à côté du travail. Là où les agents exécutent des tâches assignées, la couche de gestion du travail est l'endroit naturel : une tâche Sharkly enregistre la personne responsable du travail aux côtés de l'Agent ou de l'Équipe assignée pour l'exécuter, ce qui maintient la responsabilité humaine et l'exécution de l'agent comme deux faits distincts et visibles. La documentation Sharkly décrit cette séparation en détail. Quelle que soit la manière dont vous le stockez, la question d'audit après un incident est généralement « qui a demandé cela », et un jeton seul ne peut pas y répondre.
Ne laissez pas le modèle détenir l'identifiant
Une règle architecturale prévient la plupart des incidents d'authentification dans les systèmes d'agents : le modèle ne voit jamais de jeton.
Les jetons sont injectés par l'exécuteur au niveau de la couche HTTP, après que le modèle a choisi un outil et produit des arguments. Le schéma de l'outil n'a pas de paramètre token, l'invite ne contient aucun identifiant, et la réponse lue par le modèle a l'en-tête Authorization supprimé.
Cela est plus important pour les agents que pour les clients ordinaires en raison de la façon dont l'entrée du modèle circule. Tout ce qui est en contexte peut être résumé dans un transfert, écrit dans une trace, répercuté dans un message d'erreur, ou renvoyé à un utilisateur qui a demandé à l'agent de s'expliquer. Aucun de ces chemins n'est hostile ; ce sont toutes des fonctionnalités normales qui deviennent des fuites dès qu'un identifiant est dans le scope.
La même règle s'applique à l'identité de l'utilisateur. L'exécuteur sait pour quel utilisateur cette exécution agit, et il sélectionne le jeton correspondant. Laisser le modèle nommer l'utilisateur est une décision d'autorisation prise par le composant le moins prévisible du système.
Une liste de contrôle
- Accès délégué partout où les données appartiennent à un utilisateur, comptes de service uniquement pour vos propres ressources.
- Code d'autorisation avec PKCE au moment de la connexion, octroi d'appareil pour les machines sans interface graphique.
- Scopes demandés par agent, minimaux, escaladés de manière incrémentale.
- Les sous-agents reçoivent des jetons échangés, et non des copies de l'octroi de l'utilisateur.
- Jetons de rafraîchissement chiffrés au repos et jamais dans les invites, les journaux ou les traces.
- Rafraîchissement géré par un gestionnaire de jetons, sérialisé par utilisateur, rotation persistée.
401et403traités comme terminaux, avec un message nommant l'utilisateur et le scope.- Octrois expirés détectés et signalés à l'utilisateur, non réessayés chaque nuit.
- Actions à enjeux élevés filtrées par approbation en plus du jeton.
- Les cinq scénarios d'authentification testés contre des mocks en CI.
L'authentification déléguée demande plus de travail qu'une clé partagée, et elle vous procure les deux choses dont vous avez besoin lorsqu'un agent agit pour d'autres personnes : l'utilisateur peut la révoquer, et le journal indique qui a fait quoi. Téléchargez Apidog pour construire le flux de jetons et ses cas d'échec avant qu'un agent ne l'exécute sans surveillance.
Questions fréquemment posées
L'agent peut-il compléter lui-même le flux de consentement OAuth ? Non, et il ne devrait pas essayer. Le consentement exige qu'une personne décide ce qu'elle accorde. Faites en sorte qu'un humain autorise une fois via un flux de navigateur normal, puis laissez l'agent utiliser l'octroi qui en résulte.
Chaque agent doit-il avoir son propre client OAuth ? Des clients séparés par intégration de produit, et des jetons séparés par agent au sein de celle-ci, généralement via l'échange de jetons. Des clients distincts sont utiles lorsque les fournisseurs appliquent des limites de débit par client ou lorsque vous souhaitez une révocation indépendante.
Que se passe-t-il si le jeton de rafraîchissement pivote et que je rate le nouveau ? L'utilisateur est bloqué et doit se reconnecter. Persistez le nouveau jeton de rafraîchissement dans la même transaction qui consomme l'ancien, et sérialisez les rafraîchissements par utilisateur afin que deux workers ne puissent pas entrer en concurrence.
Est-il sûr de laisser le modèle voir un jeton d'accès ? Non. Les jetons appartiennent à la couche HTTP, injectés par votre exécuteur. Tout ce qu'un modèle voit peut se retrouver dans une trace, un résumé ou une réponse, comme abordé dans notre article sur les clés API à moindre privilège pour les agents.
Comment auditer quel agent a fait quoi ? Enregistrez l'ID de l'utilisateur, le nom de l'agent, le scope utilisé et l'identifiant du jeton sur chaque appel, jamais le jeton lui-même. Notre article sur le traçage des appels d'outils d'agent couvre la forme de l'enregistrement.
Que faire si le fournisseur ne prend pas en charge l'échange de jetons ? Stockez des octrois séparés par agent là où le fournisseur le permet, ou appliquez une limitation de scope dans votre propre passerelle afin que les appels de chaque agent soient filtrés pour n'inclure que ses opérations autorisées avant de quitter votre réseau.