Authentification des agents Module

Vaks PM · Guide d'intégration · Authentification des agents · juillet 2026

Ce que couvre ce guide. Comment un agent activé obtient le jeton court qu'il présente à chaque appel d'API — sans que vous ayez à distribuer un secret longue durée. C'est l'étape après l'existence de l'agent dans Vaks PM. Si vos agents ne sont pas encore créés, commencez par Annuaires d'agents ; ce guide suppose un agent déjà existant, détenu par un humain, avec un niveau de confiance et des capabilities définis.

Trois façons pour un agent d'obtenir un jeton

Chaque action d'agent est authentifiée par un jeton court vaks_pat_ porteur de l'identité de l'agent. Il y a trois façons de l'obtenir, qui ne diffèrent que par l'origine de la confiance :

Méthode	Ancre de confiance	Cas d'usage
Jeton manuel	Un humain émet un jeton dans l'admin et le confie à l'agent.	Quelques agents ; tout ce qui n'a pas de plateforme d'identité. Décrit dans Annuaires d'agents → Activer.
Fédération ce guide	La plateforme d'exécution de l'agent signe un jeton prouvant son identité ; Vaks PM le vérifie et l'échange. Aucun secret n'est jamais distribué.	Agents tournant sur une plateforme qui émet des identités de charge de travail : Kubernetes, Microsoft Entra (Copilot Studio, Azure AI Foundry), GitHub Actions.
Auto-service headless ce guide	L'agent détient un refresh rotatif et renouvelle ses jetons courts lui-même.	Agents sans plateforme d'identité : un runtime auto-hébergé, un script, un orchestrateur maison.

C'est une fonctionnalité sous licence. La fédération et l'auto-service headless requièrent tous deux la feature agent-federation sur votre licence. Le jeton manuel fonctionne toujours et n'est jamais un prérequis — la fédération est le confort qui supprime la gestion des secrets à l'échelle, pas une barrière pour faire tourner des agents.

Laquelle choisir

La question déterminante est simple : la plateforme qui exécute l'agent lui fournit-elle un jeton d'identité signé ?

Oui — Kubernetes projette un jeton de ServiceAccount ; Entra émet un jeton de charge de travail pour un service principal ; GitHub Actions génère un jeton OIDC par job. Utilisez la fédération. Rien n'est stocké de part et d'autre.
Non — l'agent n'est que du code que vous exécutez quelque part, sans tissu d'identité autour. Utilisez l'auto-service headless : un humain émet un identifiant durable une fois, l'agent le fait tourner ensuite indéfiniment.

L'authentification d'agent n'est pas la délégation utilisateur. Les deux voies ici produisent un jeton agent — l'agent agit comme lui-même, avec ses propres capabilities, son responsable humain attaché pour la traçabilité. C'est une surface distincte de la connexion navigateur du connecteur IA (MCP), où l'IA emprunte les droits d'un utilisateur connecté. Les deux ne partagent jamais un identifiant ni une session, et sont servies par des parties différentes de la plateforme.

Fédération — ce qu'il faut configurer dans Vaks PM

La fédération suit le standard OAuth 2.0 d'échange de jeton (RFC 8693). Vous déclarez quel émetteur vous approuvez ; l'agent présente alors un jeton de cet émetteur et reçoit en retour un jeton Vaks PM court.

Ouvrez Admin → Intégrations → Identité fédérée des agents et pressez Ajouter un émetteur. Les champs :

Champ	Quoi y mettre
Libellé	Texte libre, affiché dans la liste.
Émetteur	Le claim `iss` exact que la plateforme met dans ses jetons, au caractère près. Pour Entra : `https://login.microsoftonline.com/<tenant-id>/v2.0`.
Audience	La valeur que la plateforme placera dans le claim `aud` du jeton, ex. `api://vaks-pm/<votre-slug>`. Obligatoire — c'est le seul contrôle qui empêche un jeton obtenu par l'agent pour un autre service (Microsoft Graph par exemple) d'être accepté ici. Quel que soit votre choix, configurez la même chaîne côté plateforme.
Source d'identité	Doit correspondre à la source de l'agent : `entra-agent` pour les agents importés d'Entra, `api` pour les agents enregistrés en entrant, ou une valeur à vous pour un émetteur auto-déclaré comme `k8s`. Un agent ne peut être authentifié que par un émetteur dont la source d'identité correspond à sa provenance — une garde en profondeur.
Clés de signature	Une des trois : une URL de découverte OIDC (Vaks PM résout le jeu de clés pour vous), une URL JWKS, ou un JWKS collé. Collez le jeu de clés quand l'émetteur est interne ou isolé — la vérification ne fait alors aucun appel sortant.
Claim du sujet	Le claim portant l'identifiant de l'agent, défaut `sub`. Il doit égaler l'identifiant externe stocké de l'agent. Les jetons de charge de travail Entra le portent parfois dans `oid` — c'est le champ à ajuster si un jeton valide est rejeté comme agent inconnu.
Durée du jeton	Durée de vie du jeton émis, 300–3600 secondes.
Contraintes de claims (option)	Claims supplémentaires exigés en égalité stricte, ex. `{ "repository": "org/repo" }` pour n'accepter qu'un dépôt GitHub.
Activer cet émetteur	Tant que ce n'est pas coché, tout échange est refusé.

Pressez Tester pour confirmer que le jeu de clés est accessible. Assurez-vous ensuite que l'agent qui s'authentifiera a son identifiant externe réglé sur la valeur que la plateforme met dans le claim du sujet — c'est le lien entre le jeton signé et l'identité Vaks PM.

Dériver depuis un connecteur d'annuaire Entra. Si vous exploitez déjà un annuaire d'agents sur le même tenant Entra, le formulaire d'émetteur peut pré-remplir l'émetteur, l'audience et la source d'identité depuis lui en un clic. Les valeurs sont un instantané, pas un lien vivant : modifier le connecteur ensuite ne déplace pas l'émetteur, et l'écran vous avertit si les deux divergent.

Une fois un émetteur déclaré et l'agent activé, l'agent s'authentifie ainsi — la plateforme fournit le JWT, l'agent ne fait que le relayer :

POST /api/v1/auth/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<le JWT émis par la plateforme>
&subject_token_type=urn:ietf:params:oauth:token-type:jwt

→ { "access_token": "vaks_pat_…", "expires_in": 3600, "scope": "…" }

Le jeton renvoyé est un jeton d'agent ordinaire, borné par les capabilities de l'agent. À son expiration l'agent rééchange simplement — il n'y a aucun refresh à gérer, puisque la plateforme réémet le JWT source à la demande.

Recettes par plateforme

Le côté Vaks PM est identique partout — la déclaration d'émetteur ci-dessus. Ce qui change, c'est comment on dit à la plateforme d'émettre un jeton pour votre audience. Nous ne reproduisons pas ici la documentation propre à chaque plateforme ; les liens pointent directement vers la source qui fait foi. Dans tous les cas, la valeur que vous mettez en Audience dans Vaks PM doit être la même que celle que la plateforme est configurée pour demander.

Kubernetes & émetteurs OIDC génériques

Le cas le plus simple, et le plus propre pour un déploiement on-premise. Un pod demande un jeton de ServiceAccount projeté avec votre audience ; le kubelet l'écrit dans un fichier et le fait tourner. Dans Vaks PM, réglez l'émetteur sur l'émetteur OIDC de votre cluster et pointez l'URL JWKS dessus, ou collez le jeu de clés du cluster pour un montage totalement isolé.

Doc Kubernetes — Projection de volume de jeton de ServiceAccount.

Microsoft Copilot Studio

Un agent Copilot Studio peut agir comme lui-même dès que vous activez Entra Agent ID pour l'environnement : il reçoit un service principal Entra et s'authentifie sans secret via des federated identity credentials. Configurez son appel vers Vaks PM avec votre audience, et déclarez le tenant Entra comme émetteur ici.

Microsoft — Créer automatiquement des identités d'agent Entra.

Attention aux deux modes. Le mode par défaut des connecteurs Copilot Studio est on-behalf-of, où l'agent agit avec les permissions de l'utilisateur connecté — c'est de la délégation utilisateur, qui relève de la surface MCP, pas d'ici. La fédération ne s'applique que lorsque l'agent agit sous sa propre identité Entra. (On-behalf-of, pour référence.)

Azure AI Foundry

Un agent Foundry reçoit une identité Entra dédiée via une managed identity et un federated credential ; à l'exécution, Foundry acquiert un jeton pour cette identité, scopé à une audience downstream que vous configurez. Réglez cette audience sur votre valeur Vaks PM, et déclarez le tenant Entra comme émetteur ici. C'est le cas le plus proche du modèle d'échange de jeton — Foundry fait l'essentiel du travail avant même d'atteindre Vaks PM.

Microsoft — Concepts d'identité d'agent dans Microsoft Foundry.

GitHub Actions

Un workflow avec id-token: write peut générer un jeton OIDC court par job pour votre audience. Utilisez les contraintes de claims de l'émetteur pour l'épingler à un seul dépôt ou environnement.

GitHub — Durcissement de la sécurité avec OpenID Connect.

Supporté par conception, un essai s'impose. Les recettes Entra (Copilot Studio, Foundry) reposent sur un détail qui dépend de votre tenant : qu'Entra émette bien un jeton dont l'aud égale votre audience Vaks PM, et dont le claim de sujet égale l'identifiant externe stocké sur l'agent. Les deux sont configurables ici précisément pour que vous puissiez les aligner, mais confirmez le premier échange réussi contre votre tenant réel avant de vous en remettre à lui en production.

Auto-service headless — identifiants machine

Quand il n'y a pas de plateforme pour signer un jeton — un agent auto-hébergé, un script, un runtime maison — l'agent détient plutôt un identifiant de refresh durable et rotatif, et renouvelle ses jetons de travail courts tout seul. Un humain l'émet une fois ; ensuite aucun humain n'est dans la boucle.

Ouvrez Admin → Utilisateurs & Identité → Agents, sélectionnez l'agent, et sous Identifiants machine pressez Émettre un identifiant. Le secret (vaks_agr_…) est montré une seule fois — confiez-le au propre magasin de configuration de l'agent. L'agent boucle ensuite :

POST /api/v1/agents/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=vaks_agr_…

→ { "access_token": "vaks_pat_…",   // ~1 h, à utiliser sur chaque appel
       "refresh_token": "vaks_agr_…",  // NOUVEAU — stockez-le, l'ancien est consommé
       "expires_in": 3600 }

Deux propriétés rendent cela sûr à laisser tourner sans surveillance :

Le refresh tourne. Chaque échange renvoie un nouveau refresh et retire le précédent (après une courte fenêtre de grâce qui absorbe une réponse perdue). Présenter un jeton consommé hors de cette fenêtre est traité comme un vol : toute la chaîne d'identifiants est révoquée d'un coup et l'événement est journalisé.
Le jeton de travail reste court. Le secret de refresh ne transite que vers /agents/token ; le jeton utilisé sur les vrais appels d'API vit environ une heure. Un jeton de travail qui fuit meurt vite de lui-même.

Révoquer l'identifiant (même écran) coupe l'agent immédiatement — il faudrait qu'un humain en réémette un. Suspendre l'agent, ou son responsable humain, a le même effet à l'appel suivant.

Ce n'est pas le flux navigateur MCP. Les identifiants machine sont servis sur un endpoint dédié qui n'implique jamais de navigateur, d'écran de consentement, ni de session utilisateur. Il n'émet que des jetons d'agent. Le connecteur IA (MCP), orienté utilisateur, reste entièrement séparé.

Agents externes & leur limite d'exposition

Un agent hébergé sur une plateforme externe (Copilot Studio, Azure AI Foundry, un runtime cloud) doit joindre Vaks PM par le réseau. En déploiement on-premise, on n'expose pas l'API interne à Internet : un relais minimal et sans secret, en DMZ, est la seule porte publique, et il ne forwarde qu'une surface choisie vers l'API interne. L'API interne, la base, le cache et le stockage objet ne sont jamais joignables directement.

Ce relais trace une frontière réseau délibérée autour de ce qu'un agent hébergé à l'extérieur peut atteindre en REST, en plus des contrôles par requête. Un agent fédéré est borné deux fois :

Couche	Ce qu'elle impose
Capabilities (toujours)	Les droits effectifs d'un agent = les permissions de son rôle ∩ les scopes de son jeton ∩ ses capabilities. La finance, les données client, l'annuaire des utilisateurs, la timesheet et l'audit ne peuvent jamais être accordés à un agent, quelle que soit la route atteinte.
Allow-list réseau (déploiement DMZ durci)	Le relais ne forwarde que la surface de travail de l'agent — tâches, projets, livrables, commentaires, pièces jointes, compétences, charge, allocations, temps, runs d'agent, équipes, jours fériés. Les contrôleurs finance, clients, utilisateurs, audit et reporting ne sont pas forwardés du tout : ils ne sont même pas joignables d'Internet par ce chemin.

La limite ne concerne que le chemin REST direct. Ce resserrement s'applique à un agent qui appelle l'API REST directement à travers la DMZ. Il n'affecte pas le connecteur IA (MCP) : le serveur MCP joint l'API interne par sa propre sortie, donc une personne qui utilise les tools MCP garde tout l'éventail (borné, comme toujours, par les toggles MCP et son propre RBAC). Les deux surfaces sont indépendantes.

Le plafond des capabilities est la frontière autoritative, toujours active ; l'allow-list réseau est de la défense en profondeur pour le déploiement durci. Dans la démo, où toute l'app est internet-facing par commodité, seul le plafond des capabilities s'applique — le resserrement réseau est une propriété du relais DMZ, livré comme gabarit de déploiement (infra/dmz/) plutôt qu'activé par défaut.

Ce qui est journalisé

Tout ici laisse une trace d'audit sous Admin → Sécurité & Conformité → Journal d'audit, exportable vers votre SIEM :

Action	Enregistré
Émetteur créé, modifié, supprimé	Acteur et émetteur, en sévérité critique. Déclarer qui peut se porter garant d'un agent est une décision de racine de confiance.
Identifiant machine émis, révoqué	Acteur et agent cible, en sévérité critique. Une révocation déclenchée par un vol est enregistrée avec sa raison.
Échange réussi	En sévérité informationnelle, attribué au type d'acteur `AGENT` — un jeton est émis une fois par heure et par agent, donc c'est fréquent par conception.
Échange refusé	En sévérité avertissement, avec la raison (émetteur inconnu, mauvaise audience, rejeu, responsable inactif, etc.) — ce sont ceux-là que vous surveillez.

Voir aussi : annuaires d'agents pour créer les agents d'abord · produit & fonctionnalités pour le modèle de gouvernance des agents · connecteur IA (MCP) pour l'accès délégué utilisateur · toutes les intégrations.