Fédération d’identités de charge de travail

La fédération d’identités de charge de travail permet à une charge de travail de confiance d’utiliser une identité qu’elle possède déjà, au lieu de stocker une clé API OpenAI ou un identifiant ChatGPT. La charge de travail présente un token de courte durée émis par votre fournisseur d’identité, qu’OpenAI échange contre un token d’accès OpenAI de courte durée.

Les charges de travail de l’API OpenAI peuvent également échanger une identité vérifiée par certificat grâce à la fédération d’identités de charge de travail X.509.

Vous pouvez utiliser la fédération d’identités de charge de travail avec l’API OpenAI ou Codex :

Les deux approches utilisent le même modèle de confiance, mais leur administration et leur configuration d’exécution diffèrent. Commencez par les concepts communs et les instructions relatives aux fournisseurs d’identité ci-dessous, puis suivez la section correspondant au produit utilisé par votre charge de travail.

• API OpenAI : Passez à la section Utilisez l’identité de charge de travail avec l’API OpenAI.
• Codex : Suivez le guide Utilisez l’identité de charge de travail avec Codex pour effectuer toute la configuration dans l’Admin Portal et l’environnement d’exécution.

Les administrateurs peuvent également gérer les fournisseurs et les règles Codex avec l’API Admin. Consultez la référence des règles de fédération Codex pour comprendre le fonctionnement des règles et de leur cycle de vie.

Fonctionnement

Un administrateur configure trois éléments avant que la charge de travail ne se connecte :

1. Un fournisseur d’identité indique à OpenAI à quel émetteur externe faire confiance et comment vérifier ses tokens signés ou ses identités par certificat.
2. Une règle d’accès définit les attributs de token acceptés par OpenAI et l’identité OpenAI sous laquelle la charge de travail peut agir. Dans la configuration de l’API OpenAI, il s’agit d’une association à un compte de service. Dans celle de Codex, il s’agit d’une règle de fédération.
3. Un principal OpenAI reçoit l’accès ainsi accordé. Pour l’API OpenAI, le principal est un compte de service de la plateforme. Pour Codex, le principal est un compte utilisateur ou de service ChatGPT dans un espace de travail géré.

Lors de l’exécution :

1. La charge de travail reçoit un JWT OIDC ou un JWT-SVID SPIFFE de courte durée, ou une charge de travail de l’API OpenAI présente un certificat X.509.
2. La charge de travail présente son identité externe avec les identifiants requis par le produit qu’elle utilise.
3. OpenAI vérifie le token ou le certificat, puis évalue l’association ou la règle configurée.
4. OpenAI renvoie un token d’accès de courte durée pour le principal associé.

L’échange de tokens ne crée jamais de principal, de projet ni d’appartenance à un espace de travail. Les administrateurs créent ou sélectionnent ces ressources lors de la configuration.

Obtenez un token d’identité

Choisissez le guide correspondant à l’environnement dans lequel votre charge de travail s’exécute :

OpenAI prend en charge les tokens de sujet JWT compatibles OIDC dans les configurations documentées, y compris les JWT-SVID SPIFFE. Pour l’API OpenAI, contactez l’assistance OpenAI si votre fournisseur OIDC ne figure pas dans la liste. Pour Codex, choisissez OIDC personnalisé dans l’OpenAI Admin Portal.

Chaque guide de fournisseur OIDC explique comment émettre et inspecter un token. Pour Codex, suivez uniquement ces étapes d’émission de tokens, puis revenez à Utilisez l’identité de charge de travail avec Codex. Les instructions de configuration OpenAI et les exemples de SDK de ces guides s’appliquent à l’API OpenAI. La fédération X.509 prend uniquement en charge l’API OpenAI.

Utilisez l’identité de charge de travail avec l’API OpenAI

Suivez cette procédure lorsque votre charge de travail appelle directement l’API OpenAI. Vous devez disposer de l’autorisation de gérer les fournisseurs d’identité de charge de travail et les associations aux comptes de service de l’organisation.

Accédez à Paramètres de l’organisation > Sécurité > Fournisseur d’identité de charge de travail. Créez d’abord le fournisseur, puis configurez ses associations aux comptes de service depuis la page de détails du fournisseur.

Fournisseurs X.509

Un fournisseur X.509 dérive les attributs d’identité de charge de travail d’un certificat client qu’OpenAI vérifie à l’aide de la configuration TLS mutuel existante de votre organisation. Il ne stocke pas de certificats et ne conserve pas de magasin de confiance distinct.

Avant de créer le fournisseur, configurez et activez le certificat de confiance qui sert d’ancrage à votre certificat client dans Paramètres de l’organisation > Sécurité > TLS mutuel. Le guide du TLS mutuel explique les autorisations, les exigences relatives aux certificats, le périmètre d’activation, les hôtes mTLS, le fonctionnement des chaînes de certificats, les filtres CEL et la rotation.

Créez ensuite le fournisseur X.509, dérivez une valeur openai.subject non vide et associez cette identité à un compte de service du projet disposant uniquement des autorisations nécessaires à la charge de travail. La charge de travail présente son certificat au point de terminaison de tokens X.509 pour obtenir un token de type bearer de courte durée, puis envoie ce token et un certificat client accepté au point de terminaison mTLS de l’API.

Suivez le guide de configuration des certificats X.509 pour connaître la procédure complète dans le tableau de bord et le déroulement des requêtes.

Configurez un fournisseur d’identité de charge de travail OIDC

Créez un fournisseur d’identités de charge de travail pour chaque émetteur externe auquel vous faites confiance. L’identité de charge de travail pour l’API OpenAI prend en charge les tokens de sujet JWT OIDC. Sa configuration comprend les options suivantes :

La découverte OIDC personnalisée et le JWKS importé s’excluent mutuellement. L’activation de la découverte personnalisée masque l’option de JWKS importé. L’URL de découverte personnalisée doit être publique, utiliser HTTPS et ne contenir ni identifiants d’authentification, ni port personnalisé, ni chaîne de requête, ni fragment.

Si l’option Utilisez une URL personnalisée pour la découverte OIDC n’apparaît pas dans votre tableau de bord, utilisez la découverte OIDC standard ou activez à la place l’option Utilisez un JWKS importé pour vérifier les tokens. Utilisez le JWKS public publié par votre fournisseur d’identité et mettez-le à jour lorsque le fournisseur renouvelle ses clés de signature.

Lorsque l’émetteur du token et l’hôte de découverte diffèrent, renseignez le champ URL de l’émetteur OIDC avec la revendication iss du token et le champ URL de découverte OIDC personnalisée avec l’hôte qui publie le document de découverte du fournisseur. OpenAI continue de vérifier le token par rapport à l’émetteur configuré ; l’URL personnalisée détermine uniquement où récupérer les métadonnées de découverte et les clés publiques de signature.

Transformez les revendications des tokens avec CEL

Les transformations d’attributs utilisent Common Expression Language (CEL). OpenAI prend en charge les opérateurs CEL standard définis dans langdef.md et n’ajoute aucune fonction personnalisée de fédération d’identités de charge de travail. Chaque expression reçoit un objet racine :

• assertion : l’ensemble des revendications JWT vérifiées.

Le tableau de bord applique automatiquement le préfixe openai.. Saisissez le suffixe, par exemple subject, et une expression, par exemple assertion.sub. L’API enregistre l’attribut dérivé sous le nom openai.subject.

12345678910[
  {
    "attribute": "openai.subject",
    "expression": "assertion.sub"
  },
  {
    "attribute": "openai.repository",
    "expression": "assertion.repository"
  }
]

Utilisez la syntaxe CEL définie par la spécification du langage CEL. Par exemple, vous pouvez lire les valeurs des revendications avec des expressions comme assertion.sub ou assertion.repository. Une syntaxe ou des fonctions non prises en charge font échouer la résolution du mappage.

12345678910[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  },
  {
    "attribute": "openai.production",
    "expression": "assertion.ref == \"refs/heads/main\""
  }
]

Les résultats des transformations doivent être des valeurs scalaires : chaînes de caractères, valeurs true ou false, entiers ou nombres finis. Les tableaux, les objets, les valeurs nulles et les erreurs d’évaluation font échouer la résolution du mappage. OpenAI convertit les résultats scalaires des transformations en chaînes de caractères avant de les comparer aux valeurs du mappage. Par exemple, true devient "true" et 7 devient "7".

Les clés de mappage qui commencent par openai. sont résolues uniquement à partir des transformations d’attributs. Les revendications brutes du token de sujet qui utilisent déjà le préfixe openai. n’influencent pas les décisions de mappage, sauf si vous configurez une transformation correspondante.

Gérez les JWKS et la rotation des clés

OpenAI vérifie les tokens de sujet OIDC à l’aide de la source de clés configurée sur le fournisseur d’identités de charge de travail :

• Découverte OIDC : OpenAI récupère le document /.well-known/openid-configuration de l’émetteur, puis le contenu de l’URI jwks_uri découverte. OpenAI met en cache les documents de découverte et les données JWKS distantes pendant 600 secondes.
• Découverte OIDC personnalisée : OpenAI récupère /.well-known/openid-configuration à partir de l’URL de base de découverte personnalisée configurée, puis le contenu de l’URI jwks_uri découverte. La revendication iss du token doit toujours correspondre au champ URL de l’émetteur OIDC.
• Actualisation des clés en cas d’absence : si le kid d’un token est introuvable dans le JWKS en cache, OpenAI actualise le JWKS et relance la recherche avant de rejeter le token.
• JWKS importé : lorsque l’option Utilisez un JWKS importé pour vérifier les tokens est activée, OpenAI utilise le JWKS importé enregistré sur le fournisseur et n’effectue ni découverte OIDC ni récupération de JWKS distant. Dès qu’une mise à jour du fournisseur est disponible pour le service d’échange de tokens, les nouveaux échanges utilisent le JWKS enregistré.
• Jeux de clés : un JWKS peut contenir plusieurs clés publiques. Chaque clé doit avoir un kid unique et non vide.

Lors de la rotation des clés de signature, publiez les anciennes et les nouvelles clés publiques dans le JWKS de l’émetteur pendant toute la période de rotation. Les tokens signés avec l’ancienne clé continuent ainsi de fonctionner tandis qu’OpenAI accepte ceux signés avec la nouvelle. Pour un JWKS importé, mettez à jour le fournisseur avant d’émettre des tokens avec le nouveau kid ; OpenAI rejette les tokens signés avec une clé absente du JWKS configuré.

Configurez un mappage de compte de service

Un mappage de compte de service définit quelles identités externes peuvent générer des jetons d’accès pour un compte de service OpenAI.

Pour les fournisseurs X.509, les clés de mappage utilisent des attributs openai.* dérivés. Privilégiez un mappage exact sur openai.subject. Les revendications JWT brutes telles que sub, aud et iss s’appliquent uniquement aux fournisseurs OIDC.

Sa configuration comprend les options suivantes :

Les valeurs des attributs doivent être des valeurs JSON scalaires. Les chaînes de caractères peuvent comporter un seul caractère générique final, précédé d’un préfixe non vide, comme repo:example/*. Un caractère générique utilisé seul ou au milieu d’une valeur n’est pas pris en charge.

Valeurs valides avec un caractère générique :

• repo:openai/*
• repository:my-org/*

Valeurs non prises en charge avec un caractère générique :

• *
• repo:*:prod
• repo/*/main

Le tableau de bord affiche les restrictions du mappage sous le libellé Autorisations. Les réponses d’échange de tokens exposent ces mêmes restrictions sous forme de portées OAuth dans la propriété scope. Les mappages ne peuvent pas inclure de portées de l’API d’administration, et les règles habituelles d’autorisation des API en aval continuent de s’appliquer.

Exemple de résolution de mappage

La résolution des mappages commence une fois qu’OpenAI a vérifié l’identité externe. OpenAI recherche les mappages correspondant aux valeurs demandées de identity_provider_id et service_account_id, ignore les mappages désactivés, évalue uniquement les attributs nécessaires à chaque mappage et n’émet un jeton que si un seul mappage activé correspond à tous les attributs configurés.

Supposons qu’un jeton GitHub Actions contienne les revendications suivantes :

1234567{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "repository": "my-org/my-repo",
  "ref": "refs/heads/main"
}

Le fournisseur peut en dériver un attribut :

123456[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  }
]

Le mappage de compte de service peut alors exiger à la fois des attributs bruts et des attributs dérivés :

Les trois valeurs doivent correspondre. La valeur sub utilise un caractère générique final : elle correspond donc à toute valeur commençant par repo:my-org/my-repo:. La clé openai.repository_ref est résolue à partir de la transformation d’attribut, et non d’une revendication brute du jeton portant ce nom.

Si plusieurs mappages activés correspondent à un échange, OpenAI le rejette. OpenAI exige un mappage unique pour chaque paire (provider, service account) et ne combine pas les autorisations de différents mappages.

Connectez la charge de travail

Utilisez l’exemple de SDK de votre guide du fournisseur d’identité, ou appelez directement le point de terminaison d’échange de jetons. Pour connaître les champs de requête et de réponse, le fonctionnement des autorisations et les limites actuelles, consultez la référence de l’échange de jetons d’identité de charge de travail.

Renouvelez le token d’accès

Si vous gérez directement l’échange de tokens, conservez access_token et expires_at ensemble lorsque vous transmettez les informations d’authentification d’un service de tokens à une application. Le champ expires_at indique une date d’expiration absolue en UTC, exprimée sous forme d’horodatage Unix en secondes. Planifiez le renouvellement avant cette échéance, en tenant compte des écarts d’horloge et de la latence des requêtes.

Le champ expires_in indique la durée de validité du token en secondes à compter de son émission. Par exemple, un token émis à 12:00 UTC avec expires_in: 3600 expire à 13:00 UTC, même si un autre service le reçoit à 12:05 UTC. Les délais de transmission et de traitement ne prolongent pas la durée de validité du token. Consultez les champs de réponse pour en savoir plus.

L’échange de tokens ne renvoie pas de token de rafraîchissement. Pour renouveler le token d’accès, répétez l’échange avec un token d’identité externe ou un certificat client en cours de validité.

Utilisez l’identité de charge de travail avec Codex

Utilisez cette méthode pour les automatisations Codex de confiance dans un espace de travail ChatGPT géré. Codex associe la charge de travail à un utilisateur ou à un compte de service ChatGPT plutôt qu’à un compte de service de la Plateforme API.

Suivez le guide Utilisez l’identité de charge de travail avec Codex pour connaître la procédure complète d’administration et d’exécution. Il couvre les sources de jetons propres aux fournisseurs, les règles de fédération, la configuration requise du fichier de jeton, l’ordre de priorité des identifiants, les interfaces Codex prises en charge, la rotation et la vérification. Pour l’attribution facultative dans les journaux d’audit, Codex accepte OPENAI_WORKLOAD_IDENTITY_CONTEXT ; le guide Codex en définit le schéma, les limites en matière de confidentialité et le comportement d’audit.

Utilisez l’API d’administration pour gérer les fournisseurs et les règles Codex par programmation. La référence des règles de fédération explique comment une règle peut accepter plusieurs sujets externes tout en les associant à un seul principal ChatGPT.

Résolvez les problèmes de connexion

OpenAI rejette le jeton d’identité

Décodez le jeton localement et comparez ses revendications iss, aud, sub, exp, iat et celles propres au fournisseur avec la configuration de ce dernier. Ne collez pas de jetons de production dans des outils JWT tiers.

Pour l’API OpenAI, comparez également les attributs du jeton avec le mappage de compte de service sélectionné. Pour Codex, comparez-les avec la règle de fédération sélectionnée.

Le mappage de l’API OpenAI ne correspond pas

Vérifiez que la requête utilise les identifiants du fournisseur d’identité et du compte de service prévus, que le mappage est actif et qu’un seul mappage correspond. Consultez la référence des erreurs d’échange de jetons pour connaître le détail des catégories d’erreurs.

Codex signale une configuration incomplète

Vérifiez que le processus Codex dispose des deux variables d’environnement requises pour l’identité de charge de travail et que OPENAI_IDENTITY_TOKEN_FILE contient un chemin absolu vers un jeton en cours de validité. Vérifiez les autorisations du fichier et du répertoire parent.

Codex utilise un autre identifiant

Chargez les deux variables d’identité de charge de travail requises dans le processus Codex. La présence de l’une ou l’autre variable donne la priorité à WIF sur les clés API, les jetons d’accès et les connexions enregistrées. Démarrez un nouveau processus avec la configuration téléchargée chargée, puis exécutez à nouveau codex login status.

Recommandations de sécurité

• Utilisez un principal dédié à chaque application ou charge de travail.
• Séparez les environnements de production et hors production.
• Privilégiez une correspondance exacte des revendications plutôt que des motifs trop larges.
• N’accordez que les accès nécessaires à la charge de travail.
• Utilisez des durées de validité courtes pour les jetons d’accès.
• Examinez les fournisseurs, les mappages et les règles, et supprimez ceux qui ne sont pas utilisés.
• Examinez les erreurs d’échange de jetons et les comportements d’accès inattendus.

Documentation connexe

• Utilisez l’identité de charge de travail avec Codex
• Référence des règles de fédération de Codex
• Gérez l’identité de charge de travail de Codex avec l’API d’administration
• Référence de l’échange de jetons d’identité de charge de travail
• Authentification de Codex
• Variables d’environnement de Codex
• Mode non interactif de Codex