Autorisations de l’agent

Ce qu’un agent peut faire, qui en décide et ce que la personne qui l’exécute apporte.

Un agent intervient sur votre projet par l’intermédiaire de l’interface CLI, de l’API, de git, des connecteurs et des Apps. Cette page explique comment Beeuni détermine ce qu’un agent peut faire.

Un agent agit en son nom, et non au nom de la personne qui l’a lancé. Son autorité correspond à ses autorisations Beeuni ∩ à son rôle plafond. Les autorisations suffisent à déterminer ce qu’il peut faire, comme pour une personne. Personne ne prête son propre rôle à un agent : celui-ci agit donc de la même manière, quelle que soit la personne qui l’exécute.

L’agent est l’entité qui agit

Chaque session d’agent a deux identités :

Chaque agent a une identité par projet : un compte de service que Beeuni crée pour lui. Vous ne détenez jamais ses identifiants.

Autorisations Beeuni — le manifeste fait foi

Chaque agent déclare ses autorisations Beeuni dans beeuni.yaml, sous agents.<name>.beeuni_permissions. Le manifeste de la branche par défaut fait foi.

agents:
  report-writer:
    beeuni_permissions: [project.file.read, project.connector.read, project.app.read]
    connectors: [reports-dashboard-api]
    secrets: [REPORTS_API_KEY]
    apps: [reports-dashboard]

• La liste refuse tout par défaut. Un agent sans beeuni_permissions n’obtient aucune autorisation.
• all accorde toutes les autorisations du projet, toujours dans les limites du rôle plafond.
• beeuni_cli est l’ancienne syntaxe, désormais obsolète. Elle reste valide, avec un avertissement. Si les deux clés ont des valeurs différentes pour un même agent, la validation échoue.

Modifiez la liste dans Customize → Agents → l’agent → Beeuni permissions. L’enregistrement crée un commit de beeuni.yaml. Consultez la référence du manifeste.

Le rôle plafond — un administrateur en décide

Le rôle plafond est un rôle du projet qu’un administrateur associe au compte de service de l’agent. Les autorisations Beeuni de l’agent ne peuvent jamais le dépasser.

• Aucun rôle associé : le rôle plafond par défaut de l’agent s’applique. Il comprend toutes les autorisations du projet, à l’exception de project.credentials.issue.
• Un rôle est associé : member ou manager, un rôle prédéfini, ou un rôle personnalisé. L’agent ne conserve que les autorisations Beeuni également accordées par ce rôle.
• Un rôle plafond n’ajoute jamais d’autorisation. Un rôle plafond manager n’accorde pas à l’agent une autorisation absente de son manifeste.

Définissez le rôle plafond dans Access hub → Projects → le projet → Add. Sélectionnez l’agent sous Agents, puis choisissez un rôle. Seuls les administrateurs qui gèrent les rôles voient les agents dans le sélecteur. La liste d’accès du projet affiche le rôle plafond de chaque agent avec le badge Agent.

all signifie toutes les autorisations

beeuni_permissions: all, "*" et toute liste contenant "*" ont la même signification : toutes les autorisations du projet. Cela inclut project.members.manage (ajouter, modifier ou supprimer des membres du projet et leurs autorisations) et project.delete.

Une autorisation reste réservée aux personnes : project.credentials.issue (créer un jeton de projet ou un PAT limité au projet). Un jeton créé par un agent ne porterait aucune autorisation d’agent, et agirait donc en dehors de celles-ci. Le refus renvoie 403 avec code: "agent_human_only_action".

Une entrée qui ne correspond pas à une autorisation pouvant être accordée est ignorée à l’exécution ; le reste de la liste continue de s’appliquer. beeuni validate et une fusion de demande de modification la signalent comme erreur.

project.read est l’inverse : un agent la possède toujours au sein de son propre projet.

Exécuter un agent lui confère une autorité

La personne qui exécute un agent ne limite pas ses autorisations. Le droit d’exécuter un agent constitue donc la délégation. Beeuni vérifie « cette personne peut-elle exécuter cet agent ? » à chaque point d’entrée :

Accordez le droit « peut exécuter » dans l’onglet People de l’agent ou dans l’Access hub. Par défaut, les agents sont fermés : un membre ne peut exécuter un agent que si une attribution le désigne, lui ou l’un de ses groupes.

Les ressources personnelles restent personnelles

Une session d’agent n’accède à une ressource appartenant à une personne que si les deux conditions suivantes sont réunies :

1. La session s’exécute pour le compte de cette personne.
2. La session est privée.

Les ressources personnelles comprennent les connexions de connecteurs appartenant à un membre, les secrets personnels du projet, les clés personnelles du fournisseur et l’ordinateur de la personne. Une session partagée, une session de déclencheur ou de canal, ainsi qu’une exécution sans supervision n’accèdent à aucune de ces ressources.

Quand une autre personne envoie une invite à une session privée — par exemple, un administrateur de compte qui peut ouvrir les sessions privées des membres —, la session cesse définitivement d’agir pour le compte de son créateur. L’agent conserve ses propres autorisations. La personne qui envoie l’invite n’agit jamais par l’intermédiaire des comptes d’une autre personne.

Apps

Un agent n’ouvre une App à accès restreint ou privée que si son autorisation apps: nomme le slug de l’App ou vaut all, et que ses autorisations effectives comprennent project.app.read.

La boîte de dialogue Access de l’App répertorie les agents qui y ont accès, d’après agents.<name>.apps. Modifiez la liste dans la page Apps de l’agent (Customize → Agents → l’agent → Apps), avec beeuni agents scope <agent> --apps <slug,slug>, ou au moyen d’une demande de modification vers beeuni.yaml. La page Apps n’apparaît que si le projet a activé l’indicateur de fonctionnalité Apps.

Backends

Un projet peut posséder des backends de projet gérés. Deux autorisations les régissent. Elles suivent les autorisations Apps : un rôle qui possède project.app.read ou project.app.write possède l’autorisation Backend correspondante.

La clé d’administration donne le contrôle total des données et du code d’un Backend ; sa lecture nécessite donc project.backend.write. Le rôle prédéfini Manager possède les deux autorisations. Le rôle prédéfini Member possède project.backend.read.

Modifier des agents et des déclencheurs

beeuni.yaml détermine ce que les agents peuvent faire : toute personne qui intègre une modification à la branche par défaut détermine donc ce que les agents peuvent faire. Les mêmes autorisations s’appliquent aux agents et aux personnes :

1. La fusion d’une demande de modification nécessite project.gitops.merge.
2. Une fusion qui modifie beeuni.yaml nécessite également l’autorisation requise par la voie directe pour cette modification : agents.* → project.agent.write ; triggers → project.trigger.create, .update ou .delete ; default_agent → project.agent.write. Le rôle Manager possède ces autorisations, et l’éditeur de rôles les ajoute à tout rôle qui obtient project.gitops.merge. Le beeuni_permissions de l’agent doit les inclure ou valoir all. Un agent qui ne peut que fusionner ne peut donc pas étendre ses propres autorisations.
3. Un agent n’accorde que ce qu’il possède. Lorsqu’un agent modifie les autorisations d’un agent (dans l’éditeur d’agents, les routes de portée et d’octroi de secrets, ou une demande de modification qu’il fusionne), chaque autorisation, connecteur, secret et App ajouté doit figurer dans ses propres autorisations effectives. Pour accorder all, il doit posséder chacun de ces éléments. La restriction ou la suppression d’une autorisation est toujours permise. Un refus renvoie 403 avec code: "agent_grant_escalation".
4. Un envoi directement vers la branche par défaut contourne la demande de modification. Une session d’agent nécessite project.gitops.ref.any et toutes les autorisations du point 2. Comme le manifeste envoyé ne peut pas être vérifié avant son intégration, l’agent doit aussi posséder toutes les autorisations qu’il accorde (autorisations all, connecteurs, secrets et Apps). Sinon, il ouvre une demande de modification.
5. Un refus renvoie 403 avec code: "agent_scope_insufficient" (agent) ou "project_role_insufficient" (personne) et indique l’élément action manquant. Si le manifeste ne peut pas être lu, la fusion renvoie 503 avec code: "CR_GOVERNANCE_UNVERIFIED" et Retry-After. Réessayez.
6. Le rôle plafond est un état IAM réservé aux administrateurs. Le manifeste ne le dépasse jamais.

Comprendre un refus

Chaque 403 émis par une vérification d’autorisation comprend code et action :

Audit

Chaque action d’un agent consigne trois champs : actor désigne l’agent, on_behalf_of désigne la personne ou null, et initiator vaut human, trigger ou channel. Une exécution par déclencheur ne consigne aucune personne.

Afficher ces informations dans le tableau de bord

Ouvrez Customize → Agents → l’agent → Beeuni permissions. Le panneau What this agent can do affiche :

• les autorisations Beeuni déclarées dans beeuni.yaml,
• le rôle plafond ou Default agent ceiling,
• l’unique autorisation réservée aux personnes, project.credentials.issue,
• les autorisations effectives : « Les personnes autorisées à exécuter cet agent agissent avec ces autorisations. »

Portée

Cette page s’applique à tous les agents qu’un projet déclare sous agents: dans beeuni.yaml. Un projet sans carte agents: ne déclare aucun agent régi par ces règles ; il n’y a donc rien à activer. Il n’existe pas de retour à l’ancien modèle de rôle du lanceur.