Scopes, jetons d'API, OAuth et MCP

Consultez la référence des scopes pour chaque permission, sa description, les restrictions prises en charge et la délégation aux jetons.

L’accès programmatique doit être plus facile à révoquer et plus restreint qu’une session d’administrateur humain. Le responsable de l’automatisation définit le processus nécessaire, le responsable de la ressource approuve sa portée, et le responsable de la sécurité examine la durée de vie et le stockage des identifiants. Le succès signifie que l’intégration peut effectuer l’action prévue, se voit refuser tout le reste et peut faire l’objet d’une rotation sans interrompre des systèmes sans rapport.

Les utilisateurs gèrent leurs jetons d’API dans Profile > Authorizations > API Tokens. Les secrets ne sont affichés qu’une fois. Stockez-les dans un gestionnaire de secrets, attribuez les scopes minimaux et révoquez les jetons inutilisés.

Les clients OAuth délèguent l’autorité d’un utilisateur avec des URI de redirection explicites et un consentement. Le MCP distant utilise le même modèle de ressources et de scopes que REST et la Console ; ce n’est pas une porte dérobée privilégiée.

Utilisez des identifiants distincts pour la CI, la supervision et les outils interactifs. Évitez les jetons d’administrateur de longue durée. Limitez l’automatisation aux nœuds, Routes, charges de travail, bases de données ou projets Pages exacts dont elle est responsable.

Les identifiants d’API gw_ ordinaires et les identifiants OAuth n’entrent pas dans le plan de données Opfield Inference. Inference utilise des jetons utilisateur gwi_ dédiés.

Auditez la création, l’utilisation et la révocation des jetons. Effectuez une rotation immédiate après une divulgation suspectée et vérifiez séparément les sessions actives.

Choisir le type d’identifiant

Identifiant	Usage
Session	Accès interactif à l’Operations Console
Jeton d’API	Automatisation directe détenue par un utilisateur Opfield
Client OAuth	Autorisation déléguée d’un utilisateur et applications tierces
OAuth du MCP distant	Clients d’outils qui agissent via la surface MCP d’Opfield
Jeton d’inférence	Requêtes vers le plan de données distinct Opfield Inference

Ne substituez pas un type à un autre simplement parce qu’il est plus facile à copier. Le type d’identifiant détermine le consentement, la révocation, l’évaluation des scopes, l’objet de l’audit et la famille de points de terminaison accessible.

Créer un jeton à privilèges minimaux

1. Identifiez les opérations et les ressources exactes dont l’automatisation est responsable.
2. Créez un utilisateur ou une identité de service dédiés lorsque l’attribution doit être distincte.
3. Attribuez les scopes globaux et de ressources minimaux.
4. Créez le jeton et récupérez le secret, qui n’est affiché qu’une fois.
5. Stockez-le dans un gestionnaire de secrets et injectez-le à l’exécution.
6. Testez une requête autorisée et une requête refusée.
7. Consignez le responsable, l’objectif, l’expiration ou la rotation prévue et le système dépendant.

Évitez d’intégrer des jetons dans les URL de dépôts, l’historique des commandes, les captures d’écran ou les journaux. Une valeur masquée dans l’interface ne peut pas être récupérée plus tard ; créez un remplaçant et révoquez l’ancien jeton lorsque le secret est perdu.

Ce que les jetons peuvent et ne peuvent pas faire

Les jetons d’API et les autorisations OAuth pour l’API ou le MCP d’Opfield peuvent détenir chaque scope de permission, à l’exception d’une courte liste réservée aux utilisateurs : les scopes d’AI Workspace et des bacs à sable d’IA (ai:workspace:use, feat:ai:configure, ai:skills:manage et ai:sandbox:*), mcp:use, admin:users:impersonate et integrations:gitlab:sandbox:clone. L’accès programmatique peut donc gérer les nœuds et leur configuration, les utilisateurs et les groupes, les paramètres d’Opfield, les connecteurs d’intégrations et d’hébergeurs, les VM hébergées, les opérations Relay, les mises à jour, l’administration de l’inférence et les clés d’inférence gwi_ personnelles du propriétaire. Chaque scope délégué reste borné par les permissions actuelles du propriétaire.

Certaines actions restent liées à une session de navigateur interactive :

• la création de jetons d’API et d’autorisations OAuth, ainsi que le consentement OAuth lui-même ;
• le chat d’AI Workspace et les bacs à sable d’IA ;
• le démarrage d’une usurpation d’identité ;
• la connexion, ainsi que la modification des méthodes de connexion, de la MFA, des passkeys ou des sessions du propriétaire lui-même ; un jeton qui tente de le faire reçoit SELF_SIGN_IN_PROGRAMMATIC ;
• la gestion des identifiants GitLab personnels.

Comme les jetons peuvent désormais détenir des scopes d’administration, traitez un jeton doté de scopes d’administrateur comme un compte administrateur : donnez-lui un responsable, une expiration et, lorsque c’est possible, un périmètre de ressources restreint.

Opfield 2.11 a renommé plusieurs scopes. La création de jetons, les paramètres OAuth scope et les modifications d’autorisations OAuth acceptent encore les anciens noms pendant deux versions et enregistrent les nouveaux ; les jetons et autorisations existants ont été convertis lors de la mise à jour. Un nouveau jeton ou une nouvelle demande OAuth pour un scope comme integrations:github:manage reçoit aussi les scopes que la mise à jour lui a ajoutés (ici repo:read) lorsque vous les détenez ; l’écran de consentement les affiche et vous pouvez les décocher. Les scopes qui nécessitent une approbation manuelle, comme repo:write ou pki:ca:export, ne sont jamais ajoutés de cette façon. Voir Noms de scopes retirés.

Restreindre les jetons et les autorisations OAuth

Un jeton ou une autorisation OAuth peut être limité à des dossiers, des nœuds, des environnements d’app ou des ressources individuelles, de la même manière que les permissions d’un utilisateur. Une restriction par dossier couvre le dossier, ses sous-dossiers et les ressources qui y sont créées ou déplacées plus tard. Voir Restreindre l’accès à un dossier.

• Jetons d’API : la boîte de dialogue des jetons dans Profile > Authorizations > API Tokens présente les accès du jeton sous forme de liste. Add Access ajoute une ligne. Sur Resources, choisissez un Role, l’endroit où il s’applique (Where : Everywhere, In a project folder, In an app environment ou Specific resources) et ce qu’il couvre (Covers) ; sur Git repositories, choisissez un connecteur, les dépôts et le niveau d’accès. La boîte de dialogue ne propose que ce que vous pouvez accorder vous-même.
• Sélecteur de scopes : Review N scopes, en bas de la boîte de dialogue des jetons et de l’écran de consentement OAuth et MCP, ouvre les scopes eux-mêmes. L’en-tête de chaque section indique la portée des scopes de la section : Everywhere, un seul endroit ou N places. Cliquez dessus pour choisir parmi les dossiers, apps et environnements qui contiennent ce type de ressource. Les scopes d’une section suivent celle-ci ; Only this scope… donne à un scope sa propre restriction. Un scope que vous ne détenez que pour certaines ressources affiche No resources selected jusqu’à ce que vous les choisissiez.
• Consentement OAuth et MCP : l’écran de consentement présente ce que demande le client sous forme de lignes d’accès. Les scopes à haut risque restent hors de l’autorisation jusqu’à ce que vous les approuviez sous Review N scopes. Pour modifier plus tard les scopes et restrictions d’une autorisation existante, ouvrez-la dans Profile > Authorizations > OAuth Applications, modifiez Scopes et cliquez sur Save Scopes.
• Intégrations Git : le sélecteur de scopes restreint les scopes Git à un connecteur, un groupe ou projet GitLab, ou un propriétaire ou dépôt GitHub, avec Add groups or projects… ou Add owners or repositories… sous chaque connecteur. Un tel jeton est vérifié par rapport à sa propre restriction et à votre accès Git actuel lors de chaque opération sur un dépôt ; il cesse donc d’atteindre un dépôt dès que vous en perdez l’accès. Voir Restrictions de l’intégration Git.

Opfield développe d’abord les restrictions de dossiers et de nœuds propres au jeton, puis limite le résultat par vos accès actuels ; un jeton ne voit donc jamais plus que vous. Un droit de création ne compte jamais comme un droit de consultation lorsque vous le déléguez. Si un client demande un scope large que vous ne détenez que pour certaines ressources, Opfield restreint l’autorisation à ces ressources.

OAuth et MCP

Enregistrez des URI de redirection exactes et refusez tout comportement de redirection avec wildcard. Examinez les scopes demandés lors du consentement et séparez les clients de développement des clients de production. Le consentement laisse les scopes à haut risque décochés par défaut afin qu’ils doivent être sélectionnés explicitement — par exemple admin:system, admin:users, admin:groups, settings:opfield:edit, nodes:manage, proxy:raw:write, proxy:unrestricted, proxy:templates:manage, pki:ca:export, les identifiants système des connecteurs (integrations:*:use), integrations:ssh:use, les actions d’hébergement payantes ou destructives, storage:credentials:reveal, storage:iam, databases:backups:restore et feat:ai:use. Les outils du MCP distant utilisent les mêmes contrôles d’autorisation et la même visibilité des ressources que REST et la Console ; la découverte d’un outil n’accorde pas la permission de l’exécuter.

Traitez distinctement les échecs d’autorisation :

• 401 : authentification absente, expirée ou invalide ;
• 403 : l’identité authentifiée ne dispose pas du scope ou du droit requis ;
• 409 : l’état actuel de la ressource ou un quota entre en conflit avec l’opération ;
• 422 : la validation de la requête a échoué.

Les codes d’autorisation et jetons OAuth expirés, ainsi que les clients OAuth sans aucune autorisation depuis 90 jours, sont supprimés par la catégorie de maintenance Expired OAuth Grants ; un jeton d’actualisation (refresh token) est conservé jusqu’à son expiration afin que sa réutilisation reste détectée. Voir Maintenance et rétention.

Rotation et réponse aux incidents

Créez le remplaçant, mettez à jour le système dépendant, vérifiez qu’il est utilisé avec succès, puis révoquez l’ancien identifiant. Après une divulgation suspectée, révoquez d’abord lorsque c’est sûr sur le plan opérationnel, examinez l’activité d’audit, invalidez séparément les sessions liées et effectuez la rotation de tout secret en aval susceptible d’avoir été exposé.

Conception des scopes et responsabilité

Partez de l’opération, et non d’un nom de rôle. Listez les appels de lecture et de modification exacts dont l’intégration a besoin, puis liez les scopes de ressources à la plus petite frontière de propriété stable : un dossier, un nœud, une Route, une charge de travail, une base de données ou un projet Pages. N’ajoutez un scope global que lorsque le processus traverse réellement toutes les ressources de ce type. Séparez les permissions de consultation, d’affichage, d’export, de console, de montage, de secrets et de cycle de vie ; un accès en lecture ordinaire ne doit pas impliquer l’accès aux identifiants ou à des opérations sensibles sur les hôtes.

Chaque identifiant a besoin d’un responsable humain, d’un consommateur machine, d’un objectif, d’un environnement et d’une condition de retrait. Un jeton utilisé par la CI ne doit pas servir aussi à la session de terminal d’un opérateur. Les clients OAuth de production et hors production doivent avoir des identifiants client, des URI de redirection, des secrets et des enregistrements de consentement différents. Lorsque la responsabilité change, transférez ou remplacez l’identifiant plutôt que de le laisser rattaché au compte d’un utilisateur parti.

Vérification opérationnelle

Avant d’activer l’automatisation en production :

1. appelez un point de terminaison de lecture inoffensif avec le nouvel identifiant ;
2. effectuez une modification prévue sur une ressource jetable ;
3. prouvez qu’une ressource hors périmètre est masquée ou refusée ;
4. confirmez que l’attribution dans l’audit identifie l’utilisateur ou le client OAuth attendu ;
5. vérifiez que les valeurs des jetons, les en-têtes d’autorisation et les paramètres de rappel sont masqués dans les journaux ;
6. révoquez l’identifiant et prouvez que le consommateur échoue de manière fermée ;
7. installez le remplaçant et documentez l’ordre de rotation testé.

Révoquer un jeton d’API ne met pas automatiquement fin aux sessions de navigateur, aux autorisations OAuth, aux jetons d’inférence ni aux identifiants stockés chez des fournisseurs externes. Pendant un incident, inventoriez séparément chaque famille d’identifiants.