Référence des règles de fédération Codex

Une règle de fédération détermine quelles identités de charge de travail vérifiées peuvent agir en tant qu’utilisateur ou compte de service ChatGPT donné. OpenAI évalue uniquement la règle désignée par le processus Codex. Il ne parcourt pas toutes les règles à la recherche d’une correspondance.

Chaque règle cible un seul principal et peut accepter une ou plusieurs identités en amont. Pour accepter un ensemble de sujets dans une même règle, utilisez un préfixe de sujet suivi d’un caractère générique ou une condition CEL. Vous pouvez également créer plusieurs règles pour un même principal.

Pour la procédure de configuration, consultez Utilisez une identité de charge de travail avec Codex. Pour gérer les règles par programmation, consultez l’API d’administration des identités de charge de travail.

Structure d’une règle

Le principal doit exister et être membre de l’espace de travail avant l’échange. Une règle ne crée ni utilisateur, ni compte de service, ni appartenance à un espace de travail lorsqu’une charge de travail se connecte.

Combinaison des vérifications d’identité

Une règle peut utiliser les vérifications suivantes :

Définissez au moins une vérification de sujet, de revendication exacte ou une condition CEL. Une audience acceptée ne suffit pas à identifier une charge de travail. Si vous configurez plusieurs types de vérification, chacun doit réussir.

Les vérifications du fournisseur ont lieu en premier. Une règle ne peut pas passer outre les vérifications de l’émetteur, de la signature, de l’expiration, de la durée de validité de l’assertion, du rejeu ou des conditions CEL définies au niveau du fournisseur.

Correspondance du sujet

Utilisez un sujet exact dès lors qu’une valeur stable de sub identifie la charge de travail :

repo:example-company/payments:environment:production

Un unique * en fin de chaîne permet une correspondance par préfixe :

system:serviceaccount:production:codex-*

Le caractère générique doit être le dernier caractère et suivre un préfixe non vide. OpenAI n’accepte ni *, ni repo:*:production, ni repo/*/main.

N’utilisez pas de préfixe trop large lorsqu’une revendication plus stable permet de distinguer les charges de travail privilégiées. Par exemple, une règle GitHub devrait cibler un dépôt, un fichier de workflow, une référence ou un environnement protégé plutôt que tous les dépôts d’une organisation.

Revendications exactes

Les vérifications de revendications exactes comparent les revendications JWT de premier niveau sans convertir leurs types. Une chaîne ne correspond qu’à une chaîne identique, un booléen à un booléen identique et un nombre à la même valeur numérique. Les listes et les objets ne sont pas pris en charge comme valeurs exactes.

Par exemple :

12345{
  "repository": "example-company/payments",
  "ref": "refs/heads/main",
  "environment": "production"
}

N’incluez pas sub dans le dictionnaire des revendications exactes. Utilisez le champ du sujet ou CEL. Utilisez CEL pour les revendications imbriquées du fournisseur et les tests d’appartenance à une liste.

Conditions CEL

Les conditions CEL reçoivent le dictionnaire complet des revendications JWT vérifiées sous le nom assertion et doivent renvoyer true ou false. OpenAI prend en charge un sous-ensemble limité de CEL pour que l’évaluation des règles reste prévisible.

Pour autoriser un ensemble de sujets exacts dans une même règle :

assertion.sub in [
  "repo:example-company/payments:environment:production",
  "repo:example-company/billing:environment:production"
]

Pour exiger un dépôt et l’une de deux références :

assertion.repository == "example-company/payments" &&
assertion.ref in ["refs/heads/main", "refs/heads/release"]

Pour lire une revendication imbriquée ou facultative :

has(assertion.environment) &&
assertion.environment == "production"

Les fonctions utilitaires prises en charge comprennent has, size, contains, startsWith et endsWith. La recherche de correspondances par expression régulière, les macros d’itération sur les collections telles que all ou exists, les fonctions arbitraires et les identifiants autres que assertion ne sont pas pris en charge. Gardez les expressions courtes et privilégiez les vérifications exactes lorsqu’elles permettent d’exprimer la même politique.

Une revendication absente, une opération non prise en charge, un résultat non booléen ou une erreur d’évaluation entraîne le rejet de l’échange.

Correspondance de l’audience

Le fournisseur peut définir une seule audience attendue. Une règle peut, à la place, définir une ou plusieurs audiences acceptées. Lorsqu’une règle comporte une liste d’audiences, au moins une valeur de la revendication aud du token doit figurer dans cette liste.

Utilisez une audience dédiée à OpenAI lorsque votre fournisseur le permet. Les règles SPIFFE JWT-SVID doivent définir une audience acceptée. Une règle OIDC doit également en définir une si aucune audience n’est définie au niveau du fournisseur.

La correspondance de l’audience et les vérifications d’identité se cumulent. Une audience correspondante ne compense pas l’échec d’une vérification de sujet, de revendication exacte ou d’une condition CEL.

Cardinalité des principaux

Une règle correspond à un seul et unique principal :

many accepted external identities -> one federation rule -> one OpenAI principal

Cela permet à des réplicas de charges de travail, à des jobs ou à des sujets approuvés d’agir en tant que même utilisateur ou compte de service. Une règle ne peut toutefois pas choisir un principal différent en fonction des revendications. Créez des règles distinctes lorsque les charges de travail nécessitent des principaux, des espaces de travail, des portées ou des durées de validité de tokens différents.

Plusieurs règles peuvent cibler le même principal. Utilisez des règles distinctes lorsque vous avez besoin de gérer les cycles de vie indépendamment ou d’attribuer plus clairement les activités à chaque charge de travail dans les audits.

Portées et autorisation

La règle peut restreindre les portées OAuth du jeton d’accès émis. Elle ne peut pas accorder d’autorisations que le principal cible ou l’espace de travail ne possède pas déjà.

Si vous omettez les portées, OpenAI utilise les portées standard de Codex : openid, profile, email et l’accès local à Codex. Si vous définissez les portées via l’API d’administration, incluez chatgpt.workspace.feature.allow-codex-local-access.access et utilisez uniquement ces quatre valeurs prises en charge.

Choisissez d’abord le principal et les autorisations de l’espace de travail selon le principe du moindre privilège. Considérez les portées de la règle comme une restriction supplémentaire, et non comme la principale limite d’autorisation.

Durée de validité des jetons

Définissez la durée de validité du jeton d’accès OpenAI entre 60 et 3 600 secondes. OpenAI retient la plus courte des deux durées suivantes :

• La durée de validité restante du jeton d’identité en amont.
• La durée de validité des jetons d’accès configurée dans la règle.

Des durées plus courtes réduisent le temps pendant lequel un jeton émis peut rester valide après une modification de la politique, mais augmentent la fréquence des échanges. Une durée de 10 minutes constitue un bon point de départ, sauf si votre charge de travail nécessite un autre compromis.

Protection contre le rejeu

La protection contre le rejeu au niveau du fournisseur utilise la revendication JWT jti. Lorsqu’un administrateur active Empêcher le rejeu des assertions et que le jeton contient une valeur jti non vide, OpenAI n’accepte cette valeur jti qu’une seule fois pour ce fournisseur jusqu’à l’expiration de l’assertion.

La charge de travail doit obtenir une nouvelle assertion avec une nouvelle valeur jti avant chaque échange, y compris lors des nouvelles tentatives après un échange dont le résultat est inconnu. Les assertions sans jti restent utilisables, mais ne bénéficient pas de la protection contre le rejeu. Les valeurs jti vides, nulles ou qui ne sont pas des chaînes de caractères échouent à la validation.

Modifications, désactivation et archivage

Les modifications courantes des vérifications d’identité, des portées ou de la durée de validité des jetons s’appliquent aux nouveaux échanges. Les jetons d’accès émis avant la modification peuvent rester valides jusqu’à la fin de leur durée de validité (TTL) initiale.

La désactivation d’une règle ou d’un fournisseur bloque les nouveaux échanges et révoque les jetons d’accès OpenAI émis par leur intermédiaire. L’archivage produit le même effet et est irréversible. La modification des paramètres de confiance du fournisseur, tels que l’émetteur ou les paramètres JWKS, révoque les jetons émis avant l’activation de la nouvelle configuration de confiance.

Utilisez la désactivation pour un arrêt d’urgence ou une pause temporaire. N’archivez une ressource que lorsque vous n’en avez plus besoin.

Limites

Créez des fournisseurs distincts pour les périmètres de confiance qui nécessitent une gestion indépendante de l’émetteur, des clés, du rejeu ou du cycle de vie. Créez des règles distinctes au sein d’un même fournisseur pour les charges de travail qui partagent les mêmes paramètres de confiance, mais nécessitent des principaux ou des politiques d’accès différents.