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

La fédération d’identités de charges de travail permet à une charge de travail de confiance d’utiliser l’identité dont elle dispose déjà, sans avoir à stocker une clé API OpenAI ou un identifiant ChatGPT. La charge de travail présente un jeton de courte durée émis par votre fournisseur d’identité. OpenAI l’échange contre un jeton d’accès OpenAI de courte durée.

Les charges de travail qui utilisent l’API OpenAI peuvent également obtenir un jeton en présentant une identité vérifiée par certificat grâce à la fédération d’identités de charges de travail X.509.

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

Les deux produits utilisent le même modèle de confiance, mais leur administration et leur configuration à l’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 Utiliser une identité de charge de travail avec l’API OpenAI.
• Codex : consultez la section Utiliser une identité de charge de travail avec Codex.

Consultez la référence sur les règles de fédération de Codex pour comprendre le fonctionnement des règles et leur cycle de vie.

Fonctionnement

Avant que la charge de travail se connecte, un administrateur configure trois éléments :

1. Un fournisseur d’identité indique à OpenAI à quel émetteur externe faire confiance et comment vérifier ses jetons signés ou les identités attestées par ses certificats.
2. Une règle d’accès précise les attributs de jeton qu’OpenAI accepte et l’identité OpenAI que la charge de travail peut utiliser. Dans la configuration de l’API OpenAI, il s’agit d’un mappage de compte de service. Dans celle de Codex, il s’agit d’une règle de fédération.
3. Un principal OpenAI bénéficie de l’accès ainsi accordé. Pour l’API OpenAI, il s’agit d’un compte de service de la Plateforme API. Pour Codex, il s’agit d’un compte utilisateur ou d’un compte de service ChatGPT dans un espace de travail géré.

À l’exécution :

1. La charge de travail reçoit un jeton JWT OIDC ou un JWT-SVID SPIFFE de courte durée. Une charge de travail qui utilise l’API OpenAI peut aussi présenter un certificat X.509.
2. La charge de travail présente son identité externe ainsi que les identifiants requis par le produit utilisé.
3. OpenAI vérifie le jeton ou le certificat, puis évalue le mappage ou la règle configurés.
4. OpenAI renvoie un jeton d’accès de courte durée pour le principal associé.

L’échange de jetons ne crée jamais de principal ni de projet et n’ajoute aucun membre à un espace de travail. Les administrateurs créent ou sélectionnent ces ressources lors de la configuration.

Obtenir un jeton d’identité

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

Dans les configurations documentées, OpenAI accepte les jetons de sujet au format JWT compatibles avec OIDC, 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 le portail d’administration OpenAI.

Chaque guide consacré à un fournisseur OIDC explique comment émettre et inspecter un jeton. Pour Codex, suivez uniquement les étapes relatives à l’émission du jeton, puis revenez à la section Utiliser une identité de charge de travail avec Codex. Les instructions de configuration d’OpenAI et les exemples d’utilisation du SDK présentés dans ces guides concernent l’API OpenAI. La fédération X.509 fonctionne uniquement avec l’API OpenAI.

Utiliser une identité de charge de travail avec l’API OpenAI

Suivez cette procédure si votre charge de travail appelle directement l’API OpenAI. Vous devez disposer des autorisations nécessaires pour gérer les fournisseurs d’identité de charge de travail et les mappages de comptes de service de l’organisation.

Ouvrez Paramètres de l’organisation > Sécurité > Fournisseur d’identité de charge de travail. Créez d’abord le fournisseur, puis configurez les mappages de comptes de service depuis sa page de détails.

Fournisseurs X.509

Un fournisseur X.509 déduit les attributs d’identité de la charge de travail d’un certificat client qu’OpenAI vérifie à l’aide de la configuration TLS mutuel existante de votre organisation. Le fournisseur ne stocke aucun certificat et ne gère aucun magasin de confiance distinct.

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

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

Suivez le guide de configuration des certificats X.509 pour effectuer toutes les étapes dans le tableau de bord et envoyer les requêtes correspondantes.

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

Créez un fournisseur d’identité de charge de travail pour chaque émetteur externe auquel vous faites confiance. Pour authentifier les charges de travail, l’API OpenAI accepte les jetons de sujet JWT OIDC. La configuration du fournisseur comprend les options suivantes :

La découverte OIDC personnalisée et l’utilisation d’un JWKS importé s’excluent mutuellement. Si vous activez la découverte personnalisée, l’option d’importation d’un JWKS est masquée. L’URL de découverte personnalisée doit être une URL HTTPS publique. Elle ne peut contenir ni identifiants, ni port personnalisé, ni chaîne de requête, ni fragment.

Si l’option Utiliser 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 Utiliser un JWKS importé pour vérifier les jetons. Utilisez le JWKS public publié par votre fournisseur d’identité et mettez-le à jour lorsque le fournisseur renouvelle ses clés de signature.

Si l’émetteur du jeton et l’hôte de découverte diffèrent, renseignez URL de l’émetteur OIDC avec la valeur de la revendication iss du jeton et URL de découverte OIDC personnalisée avec l’URL de l’hôte qui publie le document de découverte du fournisseur. OpenAI vérifie toujours que le jeton correspond à l’émetteur configuré. L’URL personnalisée détermine uniquement où OpenAI récupère les métadonnées de découverte et les clés publiques de signature.

Transformer les revendications du jeton avec CEL

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

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

Le tableau de bord ajoute 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 définie dans la spécification du langage CEL. Vous pouvez par exemple lire la valeur d’une revendication avec une expression telle que assertion.sub ou assertion.repository. Si vous utilisez une syntaxe ou une fonction non prise en charge, la résolution du mappage échoue.

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

Les transformations doivent produire des valeurs scalaires : chaînes de caractères, booléens 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 en chaînes de caractères avant de les comparer aux valeurs du mappage. Par exemple, true devient "true" et 7 devient "7".

Pour résoudre les clés de mappage qui commencent par openai., OpenAI utilise uniquement les transformations d’attributs. Une revendication brute du jeton de sujet dont le nom commence déjà par openai. n’a aucun effet sur le choix du mappage, sauf si vous configurez une transformation correspondante.

Gérer le JWKS et la rotation des clés

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

• Découverte OIDC : OpenAI récupère le document /.well-known/openid-configuration de l’émetteur, puis les clés à l’adresse jwks_uri indiquée dans ce document. OpenAI conserve les documents de découverte et les données des JWKS distants en cache pendant 600 secondes.
• Découverte OIDC personnalisée : OpenAI récupère /.well-known/openid-configuration à partir de l’URL de base configurée pour la découverte personnalisée, puis les clés à l’adresse jwks_uri indiquée dans ce document. La revendication iss du jeton doit toujours correspondre à la valeur du champ URL de l’émetteur OIDC.
• Actualisation en cas de clé introuvable : si le kid d’un jeton ne figure pas dans le JWKS en cache, OpenAI actualise le JWKS et relance la recherche avant de rejeter le jeton.
• JWKS importé : lorsque l’option Utiliser un JWKS importé pour vérifier les jetons est activée, OpenAI utilise le JWKS enregistré dans la configuration du fournisseur, sans effectuer de découverte OIDC ni récupérer de JWKS distant. Dès que le service d’échange de jetons dispose de la configuration mise à jour du fournisseur, 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 transition. Les jetons signés avec l’ancienne clé restent ainsi utilisables pendant qu’OpenAI accepte les jetons signés avec la nouvelle clé. Si vous utilisez un JWKS importé, mettez à jour le fournisseur avant d’émettre des jetons portant le nouveau kid. OpenAI rejette les jetons signés avec une clé absente du JWKS configuré.

Configurer un mappage de compte de service

Un mappage de compte de service définit les identités externes qui peuvent obtenir des jetons d’accès pour un compte de service OpenAI.

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

La configuration du mappage comprend les options suivantes :

Les valeurs d’attribut doivent être des valeurs JSON scalaires. Une chaîne de caractères peut se terminer par un seul caractère générique précédé d’un préfixe non vide, comme dans repo:example/*. Un caractère générique employé seul ou placé 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 Autorisations. Les réponses aux requêtes d’échange de jetons indiquent 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. Les contrôles d’autorisation habituels continuent de s’appliquer aux appels ultérieurs à l’API.

Exemple de résolution d’un mappage

La résolution du mappage commence une fois qu’OpenAI a vérifié l’identité externe. OpenAI recherche les mappages correspondant aux valeurs de identity_provider_id et de service_account_id indiquées dans la requête. Il ignore les mappages désactivés et évalue uniquement les attributs nécessaires à chaque mappage. Il n’émet un jeton que si un seul mappage actif 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 imposer des conditions à la fois sur des attributs bruts et sur un attribut dérivé :

Les trois valeurs doivent correspondre. La valeur configurée pour sub se termine par un caractère générique. Elle accepte donc toute valeur qui commence par repo:my-org/my-repo:. Pour la clé openai.repository_ref, OpenAI utilise le résultat de la transformation d’attribut, et non une revendication brute du jeton portant ce nom.

Si plusieurs mappages actifs correspondent à une demande d’échange, OpenAI la rejette. OpenAI impose un mappage unique pour chaque paire (provider, service account) et ne cumule pas les autorisations de différents mappages.

Connecter la charge de travail

Utilisez l’exemple de code du SDK dans le guide de votre 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 sur l’échange de jetons d’identité de charge de travail.

Renouveler le jeton d’accès

Si vous gérez directement l’échange de jetons, transmettez access_token et expires_at ensemble lorsque votre service de jetons fournit l’identifiant à une application. Le champ expires_at indique la date et l’heure absolues d’expiration en UTC, sous forme d’horodatage Unix en secondes. Planifiez le renouvellement avant cette échéance en tenant compte des écarts entre les horloges et de la latence des requêtes.

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

L’échange de jetons ne renvoie pas de jeton d’actualisation. Pour renouveler le jeton d’accès, répétez l’échange avec un jeton d’identité externe valide ou un certificat client valide.

Utiliser une identité de charge de travail avec Codex

Suivez cette procédure pour exécuter des automatisations Codex de confiance dans un espace de travail ChatGPT géré. Codex associe la charge de travail à un compte utilisateur ou à un compte de service ChatGPT plutôt qu’à un compte de service de la Plateforme API.

La référence sur les règles de fédération explique comment une règle peut accepter plusieurs sujets externes et les associer à un seul principal ChatGPT.

Résoudre les problèmes de connexion

OpenAI rejette le jeton d’identité

Décodez le jeton localement. 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.

Aucun mappage de l’API OpenAI ne correspond

Vérifiez que la requête contient les identifiants du fournisseur d’identité et du compte de service voulus, que le mappage est actif et qu’un seul mappage correspond. Pour le détail des catégories d’erreurs, consultez la référence sur les erreurs d’échange de jetons.

Codex signale une configuration incomplète

Vérifiez que les deux variables d’environnement requises pour l’identité de charge de travail sont définies dans le processus Codex et que OPENAI_IDENTITY_TOKEN_FILE contient le chemin absolu d’un fichier contenant un jeton en cours de validité. Vérifiez les droits d’accès au fichier et à son 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 donne la priorité à la fédération d’identités de charges de travail (WIF) sur les clés API, les jetons d’accès et les identifiants de connexion enregistrés. Démarrez un nouveau processus avec la configuration téléchargée, puis exécutez de nouveau codex login status.

Recommandations de sécurité

• Utilisez un principal dédié pour chaque application ou charge de travail.
• Séparez les environnements de production des autres environnements.
• Privilégiez les correspondances exactes sur les revendications plutôt que les motifs trop larges.
• Accordez uniquement les accès nécessaires à la charge de travail.
• Limitez la durée de vie des jetons d’accès.
• Passez en revue les fournisseurs, les mappages et les règles, puis supprimez ceux qui ne sont plus utilisés.
• Examinez les erreurs d’échange de jetons et les comportements d’accès inattendus.

Documentation associée

• Référence sur les règles de fédération de Codex
• Référence sur l’échange de jetons d’identité de charge de travail
• Authentification de Codex
• Variables d’environnement de Codex
• Mode non interactif de Codex