Configurez la fédération d’identités de charge de travail avec des certificats X.509

La fédération d’identités de charge de travail X.509 permet à une charge de travail d’échanger une identité issue d’un certificat client TLS contre un jeton d’accès OpenAI à courte durée de vie. La charge de travail appelle ensuite l’API OpenAI avec le jeton d’accès et un certificat client accepté. Ce flux remplace la clé API, mais pas le certificat client.

Pour connaître les détails des requêtes et des réponses d’échange de tokens, consultez la référence de l’échange de tokens d’identité de charge de travail. Pour les autorisations TLS mutuel, les exigences relatives aux certificats, l’activation, les hôtes mTLS et la rotation, consultez le guide TLS mutuel.

Fonctionnement

Un échange d’identité de charge de travail X.509 comporte cinq étapes :

1. Votre organisation importe et active un certificat racine de confiance dans ses paramètres TLS mutuel existants.
2. Un fournisseur d’identités de charge de travail X.509 dérive des attributs openai.* du certificat client vérifié. Il doit produire une valeur openai.subject non vide.
3. Un mappage de compte de service autorise l’identité dérivée à utiliser un compte de service OpenAI au sein d’un projet.
4. La charge de travail présente son certificat au point de terminaison de tokens X.509 sur mtls.auth.openai.com et demande un jeton au porteur à courte durée de vie. Le certificat provient de la connexion TLS ; le corps de la requête ne contient pas de subject_token.
5. La charge de travail présente le jeton au porteur et un certificat client à une route d’API sur mtls.api.openai.com pour obtenir l’autorisation d’accéder à l’API.

Le jeton au porteur et le certificat font l’objet de contrôles d’autorisation indépendants lors de la requête API. Un certificat seul n’autorise pas un appel à l’API OpenAI.

Avant de commencer

Vous avez besoin des éléments suivants :

• L’autorisation de gérer les certificats TLS mutuel et les fournisseurs d’identités de charge de travail de votre organisation.
• Un projet et un compte de service pour la charge de travail.
• Un certificat client, sa clé privée et les certificats intermédiaires nécessaires pour établir une chaîne jusqu’à votre racine de confiance.
• Un certificat racine de confiance actif au niveau de l’organisation ou du projet.

Conservez les clés privées hors du système de gestion de versions et réservez leur accès à la charge de travail qui les utilise. Ne consignez pas les clés privées, le contenu des certificats ni les jetons d’accès renvoyés dans les journaux.

Configurez la confiance des certificats TLS mutuel

Les fournisseurs d’identités de charge de travail X.509 réutilisent la configuration existante des certificats TLS mutuel de votre organisation. Ils n’importent pas de certificats et ne gèrent pas de magasin de certificats de confiance distinct.

Suivez le guide TLS mutuel pour consulter les exigences relatives aux certificats, les hôtes mTLS, le comportement de l’activation des certificats, les filtres CEL et la configuration du client. Ouvrez ensuite Paramètres de l’organisation > Sécurité > TLS mutuel, importez le certificat de confiance au format PEM et activez-le pour l’organisation ou pour chaque projet qui utilisera la fédération d’identités de charge de travail X.509.

Si la chaîne de votre certificat client passe par un certificat intermédiaire, configurez l’ancre de confiance stable et présentez le certificat feuille suivi des certificats intermédiaires actuels lors de la négociation TLS. OpenAI utilise les certificats intermédiaires fournis par la requête et ne récupère pas ceux qui manquent à partir des URL des certificats.

Configurez un fournisseur X.509

Pour configurer un fournisseur X.509 :

1. Ouvrez Paramètres de l’organisation > Sécurité > Fournisseur d’identités de charge de travail, puis sélectionnez Créer un fournisseur d’identités.
2. Choisissez X.509 comme Type de fournisseur, puis saisissez un nom et, si vous le souhaitez, une description. Les fournisseurs X.509 n’utilisent pas les paramètres d’émetteur OIDC, d’audience, de découverte ou de JWKS. Vous ne pouvez pas modifier le type du fournisseur après sa création.
3. Sous Avancé, ajoutez si nécessaire une expression CEL dans Conditions sur les attributs pour rejeter les certificats avant la résolution du mappage.
4. Sous Transformations d’attributs, saisissez une expression non vide pour la transformation obligatoire openai.subject. Le tableau de bord ajoute la ligne subject lorsque vous sélectionnez X.509, puis affiche et applique le préfixe openai.. Choisissez une donnée stable du certificat qui identifie la charge de travail.
5. Ajoutez si nécessaire des transformations portant d’autres noms openai.* uniques, puis sélectionnez Créer.

Par exemple, cette configuration utilise le nom commun du certificat comme sujet canonique et expose l’unité organisationnelle comme attribut de mappage supplémentaire :

12345678910[
  {
    "attribute": "openai.subject",
    "expression": "assertion.subject.common_name"
  },
  {
    "attribute": "openai.environment",
    "expression": "assertion.subject.organizational_unit"
  }
]

Les données du certificat sont disponibles sous assertion.subject et assertion.subject_alt_names. Les résultats des transformations utilisés pour les mappages doivent être des valeurs scalaires. Les transformations supplémentaires doivent porter des noms openai.* uniques.

Par exemple, une expression dans Conditions sur les attributs peut limiter le fournisseur aux certificats de production :

assertion.subject.organizational_unit == "Production"

Créez un mappage de compte de service

1. Sur la page des détails du fournisseur X.509, sélectionnez Créer un mappage.
2. Sélectionnez le projet et le compte de service cibles, et accordez uniquement les autorisations API dont la charge de travail a besoin.
3. Dans les champs Clé et Valeur , exigez une valeur openai.subject exacte. Les mappages X.509 acceptent soit l’absence d’assertions, représentée par un objet vide ({}), soit des assertions dont les clés commencent par openai..
4. Sélectionnez Créer.

Par exemple :

Les mappages X.509 utilisent les attributs dérivés openai.*. Ils n’effectuent pas de correspondance avec les revendications JWT brutes telles que sub, iss ou aud.

La liste des fournisseurs affiche l’identifiant du fournisseur, et les détails du mappage affichent le compte de service sélectionné ainsi que son identifiant. Notez ces deux identifiants ; la charge de travail les envoie lors de l’échange de tokens.

Utilisez l’identité de charge de travail X.509 avec un SDK

Définissez des variables d’environnement pour la chaîne de certificats, la clé privée, le fournisseur et le compte de service :

1234export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"
export OPENAI_IDENTITY_PROVIDER_ID="idp_example"
export OPENAI_SERVICE_ACCOUNT_ID="svc_acct_example"

Le fichier de chaîne de certificats doit contenir d’abord le certificat feuille, suivi des éventuels certificats intermédiaires. N’incluez ni données de certificat ni subject_token dans le corps de la requête.

Configurez un client du SDK OpenAI avec ces valeurs. Le SDK présente le certificat client lors de l’échange de tokens et des requêtes API, achemine les requêtes API vers le point de terminaison mTLS et renouvelle automatiquement les jetons d’accès à courte durée de vie.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39import { readFile } from "node:fs/promises";

import OpenAI from "openai";
import { workloadIdentity } from "openai/auth/x509-transport";

const certificatePath = process.env.OPENAI_MTLS_CERT_CHAIN;
const privateKeyPath = process.env.OPENAI_MTLS_KEY;
const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;

if (
  !certificatePath ||
  !privateKeyPath ||
  !identityProviderId ||
  !serviceAccountId
) {
  throw new Error(
    "Set OPENAI_MTLS_CERT_CHAIN, OPENAI_MTLS_KEY, OPENAI_IDENTITY_PROVIDER_ID, and OPENAI_SERVICE_ACCOUNT_ID"
  );
}

const credential = workloadIdentity.fromX509({
  certificateChain: await readFile(certificatePath, "utf8"),
  privateKey: await readFile(privateKeyPath, "utf8"),
  identityProviderId,
  serviceAccountId,
});

try {
  const client = new OpenAI({ credential });
  const response = await client.responses.create({
    model: "gpt-5.6-terra",
    input: "Say hello from X.509 workload identity federation.",
  });

  console.log(response.output_text);
} finally {
  await credential.close();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import os
import ssl

from openai import DefaultHttpx2Client, OpenAI
from openai.auth import x509_workload_identity

tls_context = ssl.create_default_context()
tls_context.load_cert_chain(
    certfile=os.environ["OPENAI_MTLS_CERT_CHAIN"],
    keyfile=os.environ["OPENAI_MTLS_KEY"],
)

with OpenAI(
    base_url="https://mtls.api.openai.com/v1",
    workload_identity=x509_workload_identity(
        identity_provider_id=os.environ["OPENAI_IDENTITY_PROVIDER_ID"],
        service_account_id=os.environ["OPENAI_SERVICE_ACCOUNT_ID"],
    ),
    http_client=DefaultHttpx2Client(verify=tls_context, follow_redirects=False),
) as client:
    response = client.responses.create(
        model="gpt-5.6-terra",
        input="Say hello from X.509 workload identity federation.",
    )

    print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"
	"net/http"
	"os"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/auth"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	certificate, err := tls.LoadX509KeyPair(
		os.Getenv("OPENAI_MTLS_CERT_CHAIN"),
		os.Getenv("OPENAI_MTLS_KEY"),
	)
	if err != nil {
		log.Fatal(err)
	}

	transport, err := auth.NewX509Transport(&http.Transport{
		TLSClientConfig: &tls.Config{
			Certificates: []tls.Certificate{certificate},
			MinVersion:   tls.VersionTLS12,
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	defer transport.Close()

	client := openai.NewClient(
		option.WithX509WorkloadIdentity(auth.X509WorkloadIdentity{
			IdentityProviderID: os.Getenv("OPENAI_IDENTITY_PROVIDER_ID"),
			ServiceAccountID:   os.Getenv("OPENAI_SERVICE_ACCOUNT_ID"),
			Transport:          transport,
		}),
	)

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5.6-terra",
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("Say hello from X.509 workload identity federation."),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.client.okhttp.X509Transport;
import com.openai.client.okhttp.X509WorkloadIdentity;
import com.openai.models.responses.ResponseCreateParams;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyStore;
import java.time.Duration;
import java.util.Arrays;
import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.TrustManagerFactory;
import javax.net.ssl.X509ExtendedKeyManager;
import javax.net.ssl.X509TrustManager;

char[] password = System.getenv("OPENAI_X509_KEYSTORE_PASSWORD").toCharArray();
try {
  KeyStore keyStore = KeyStore.getInstance("PKCS12");
  try (InputStream input =
      Files.newInputStream(Paths.get(System.getenv("OPENAI_X509_KEYSTORE_PATH")))) {
    keyStore.load(input, password);
  }

  KeyManagerFactory keyManagers =
      KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
  keyManagers.init(keyStore, password);
  X509ExtendedKeyManager keyManager =
      Arrays.stream(keyManagers.getKeyManagers())
          .filter(X509ExtendedKeyManager.class::isInstance)
          .map(X509ExtendedKeyManager.class::cast)
          .findFirst()
          .orElseThrow(() -> new IllegalStateException("No X.509 key manager available"));

  TrustManagerFactory trustManagers =
      TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
  trustManagers.init((KeyStore) null);
  X509TrustManager trustManager =
      Arrays.stream(trustManagers.getTrustManagers())
          .filter(X509TrustManager.class::isInstance)
          .map(X509TrustManager.class::cast)
          .findFirst()
          .orElseThrow(() -> new IllegalStateException("No X.509 trust manager available"));

  X509Transport transport =
      X509Transport.builder()
          .keyManager(keyManager)
          .certificateAlias(System.getenv("OPENAI_X509_CERTIFICATE_ALIAS"))
          .trustManager(trustManager)
          .build();
  X509WorkloadIdentity identity =
      X509WorkloadIdentity.builder()
          .identityProviderId(System.getenv("OPENAI_IDENTITY_PROVIDER_ID"))
          .serviceAccountId(System.getenv("OPENAI_SERVICE_ACCOUNT_ID"))
          .transport(transport)
          .refreshBuffer(Duration.ofMinutes(10))
          .build();

  OpenAIClient client = OpenAIOkHttpClient.builder().x509WorkloadIdentity(identity).build();
  try {
    ResponseCreateParams params =
        ResponseCreateParams.builder()
            .model("gpt-5.6-terra")
            .input("Say hello from X.509 workload identity federation.")
            .build();

    client.responses().create(params).output().stream()
        .flatMap(item -> item.message().stream())
        .flatMap(message -> message.content().stream())
        .flatMap(content -> content.outputText().stream())
        .forEach(outputText -> System.out.println(outputText.text()));
  } finally {
    client.close();
  }
} finally {
  Arrays.fill(password, '\0');
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32require "openai"
require "openssl"

certificate_chain = OpenSSL::X509::Certificate.load(
  File.binread(ENV.fetch("OPENAI_MTLS_CERT_CHAIN"))
)
certificate, *intermediates = certificate_chain
private_key = OpenSSL::PKey.read(File.binread(ENV.fetch("OPENAI_MTLS_KEY")))

http_client = OpenAI::NetHTTPClient.new do |connection|
  connection.cert = certificate
  connection.extra_chain_cert = intermediates
  connection.key = private_key
end

workload_identity = OpenAI::Auth::X509WorkloadIdentity.new(
  identity_provider_id: ENV.fetch("OPENAI_IDENTITY_PROVIDER_ID"),
  service_account_id: ENV.fetch("OPENAI_SERVICE_ACCOUNT_ID"),
  http_client: http_client
)

begin
  client = OpenAI::Client.new(api_key: nil, workload_identity: workload_identity)
  response = client.responses.create(
    model: "gpt-5.6-terra",
    input: "Say hello from X.509 workload identity federation."
  )

  puts(response.output_text)
ensure
  http_client.close
end

Ces exemples nécessitent des versions du SDK OpenAI prenant en charge la configuration X.509 présentée ici : JavaScript 7.8.0 ou version ultérieure avec la dépendance pair undici installée, Python 3.6.0 ou version ultérieure, Go 3.54.0 ou version ultérieure, Java 4.55.0 ou version ultérieure et Ruby 0.83.0 ou version ultérieure.

L’exemple Java charge un magasin de clés PKCS12 pour construire son X509ExtendedKeyManager et utilise le magasin de certificats de confiance par défaut de la plateforme pour construire son X509TrustManager. Définissez OPENAI_X509_KEYSTORE_PATH, OPENAI_X509_KEYSTORE_PASSWORD et OPENAI_X509_CERTIFICATE_ALIAS pour cet exemple. Vous pouvez aussi fournir au SDK des gestionnaires s’appuyant sur des fichiers PEM ou sur du matériel.

Échangez le certificat manuellement

Pour examiner ou implémenter directement le protocole d’échange de tokens, présentez le certificat au point de terminaison de tokens X.509 :

123456789101112curl --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --request POST "https://mtls.auth.openai.com/oauth/token" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token_type": "urn:openai:params:oauth:token-type:x509",
  "identity_provider_id": "${OPENAI_IDENTITY_PROVIDER_ID}",
  "service_account_id": "${OPENAI_SERVICE_ACCOUNT_ID}"
}
JSON

Un échange réussi renvoie un jeton au porteur ordinaire à courte durée de vie :

12345678{
  "access_token": "eyJ...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": 1789045200,
  "scope": "api.model.read api.model.request"
}

La propriété scope n’est renvoyée que si le mappage de compte de service correspondant dispose d’autorisations.

Les valeurs d’expiration sont fournies à titre d’exemple. La durée de validité renvoyée peut être plus courte si le certificat client vérifié expire plus tôt. Consultez les champs de la réponse d’échange de tokens pour connaître les unités et la signification de expires_in et de expires_at.

Récupérez la valeur access_token de la réponse réussie et enregistrez-la dans le magasin d’identifiants de votre application ou dans une variable d’environnement telle que OPENAI_WIF_ACCESS_TOKEN. Traitez-la comme un secret : ne l’affichez pas, ne la consignez pas dans les journaux et ne l’ajoutez pas à un commit.

Appelez l’API OpenAI manuellement

Définissez OPENAI_MODEL sur gpt-6-astra, le modèle par défaut actuel, ou sur un autre modèle disponible pour le projet cible. Envoyez ensuite le jeton au porteur et un certificat client accepté au point de terminaison mTLS de l’API :

1234567curl --request POST \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer $OPENAI_WIF_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{\"model\":\"$OPENAI_MODEL\",\"input\":\"Say hello in one sentence.\"}" \
  "https://mtls.api.openai.com/v1/responses"

Utilisez le jeton au porteur à la place d’une clé API et continuez à présenter un certificat client accepté lors de la requête API.

Le jeton au porteur n’est pas lié cryptographiquement au certificat. Réutiliser le certificat d’échange pour la requête API est la configuration la plus simple, mais la requête API peut utiliser un autre certificat qui satisfait indépendamment à la même politique mTLS de l’API en vigueur.

Durée de validité et renouvellement des tokens

Un token d’identité de charge de travail X.509 expire au bout d’une heure au maximum et jamais après le certificat client vérifié. L’échange ne renvoie pas de token de renouvellement. Répétez l’échange de certificat pour obtenir un autre token d’accès.

Pour les échanges manuels, conservez expires_at avec le token d’accès et planifiez un nouvel échange avant l’instant indiqué. Tenez compte des écarts d’horloge et de la latence des requêtes. Consultez les recommandations sur le renouvellement des tokens pour voir un exemple.

La rotation d’un certificat intermédiaire ne nécessite pas de modifier le certificat racine configuré. Présentez la nouvelle chaîne complète lors des échanges et des requêtes API suivants.

Résolution des problèmes d’échange de tokens

L’échange de tokens X.509 renvoie des erreurs OAuth génériques et ne divulgue aucun détail sur le certificat, le certificat racine, le fournisseur ou le mappage.

Un échange X.509 ne bascule jamais vers un flux OIDC ou OAuth classique en cas d’échec.

Limites

• Les fournisseurs d’identité de charge de travail X.509 ne gèrent pas de magasin de certificats de confiance distinct.
• Le token porteur n’est pas lié au certificat et n’utilise ni DPoP ni attribut cnf.
• L’échange de certificat ne permet pas d’autoriser les requêtes API sur la seule base du certificat. Les requêtes API nécessitent toujours le token porteur et un certificat client accepté.
• OpenAI ne récupère pas les certificats intermédiaires manquants à partir des URL AIA. Présentez la chaîne complète lors de la négociation TLS.
• OpenAI ne vérifie ni les listes de révocation de certificats (CRL) ni le statut OCSP dans ce flux. Prévoyez votre réponse aux incidents liés aux certificats en vous appuyant sur les contrôles des certificats racines TLS mutuel, des fournisseurs et des mappages, ainsi que sur la courte durée de validité des tokens émis.
• Ce flux n’ajoute pas la prise en charge des X.509-SVID SPIFFE. Le guide SPIFFE continue d’utiliser des JWT-SVID.