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

La fédération d’identités de charges de travail X.509 permet à une charge de travail d’échanger l’identité issue d’un certificat client TLS contre un jeton d’accès OpenAI de courte durée. La charge de travail présente ensuite le jeton d’accès et un certificat client accepté à chaque appel à l’API OpenAI. Dans ce flux, le jeton remplace la clé API. Le certificat client reste nécessaire.

Pour connaître le format de la requête et de la réponse, consultez la référence sur l’échange de jetons d’identité de charges de travail. Le guide du TLS mutuel détaille les autorisations, les exigences relatives aux certificats, leur activation et leur rotation, ainsi que les hôtes mTLS.

Fonctionnement

L’échange d’une identité de charge de travail X.509 se déroule en 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 charges de travail X.509 dérive les attributs openai.* du certificat client vérifié. Il doit en dériver une seule valeur openai.subject non vide.
3. Une règle de correspondance autorise l’identité ainsi obtenue à utiliser un seul compte de service OpenAI au sein d’un projet.
4. La charge de travail présente son certificat au point de terminaison d’échange de jetons X.509 sur mtls.auth.openai.com et demande un jeton au porteur de courte durée. Le certificat est transmis lors de la connexion TLS. Le corps de la requête ne contient pas de subject_token.
5. Pour obtenir l’autorisation d’appeler l’API, la charge de travail présente le jeton au porteur et un certificat client à une route de l’API sur mtls.api.openai.com.

Lors de la requête, l’API vérifie séparément que le jeton au porteur et le certificat sont autorisés. Le certificat seul ne suffit pas à autoriser 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 charges 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 tous 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. N’inscrivez dans les journaux ni les clés privées, ni le contenu des certificats, ni les jetons d’accès renvoyés.

Configurer les certificats de confiance pour le TLS mutuel

Les fournisseurs d’identités de charges de travail X.509 réutilisent la configuration 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.

Consultez le guide du TLS mutuel pour connaître les exigences relatives aux certificats, les hôtes mTLS, le fonctionnement 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 charges de travail X.509.

Si la chaîne de votre certificat client passe par un certificat intermédiaire, configurez un point d’ancrage de confiance stable. Lors de la négociation TLS, présentez le certificat final suivi des certificats intermédiaires en vigueur. OpenAI utilise les certificats intermédiaires fournis dans la requête et ne récupère pas les certificats manquants à partir des URL indiquées dans les certificats.

Configurer un fournisseur X.509

Pour configurer un fournisseur X.509 :

1. Ouvrez Paramètres de l’organisation > Sécurité > Fournisseur d’identités de charges 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 aucun des paramètres OIDC relatifs à l’émetteur, à l’audience, à la découverte ou au JWKS. Une fois le fournisseur créé, vous ne pouvez plus modifier son type.
3. Dans Paramètres avancés, vous pouvez ajouter une expression CEL dans Conditions sur les attributs pour rejeter certains certificats avant la recherche d’une correspondance.
4. Dans Transformations d’attributs, saisissez une expression non vide pour la transformation obligatoire openai.subject. Lorsque vous sélectionnez X.509, le tableau de bord ajoute la ligne subject, affiche le préfixe openai. et l’applique. Choisissez une caractéristique stable du certificat qui identifie la charge de travail.
5. Si nécessaire, ajoutez d’autres transformations en attribuant à chacune un nom openai.* unique, puis sélectionnez Créer.

Par exemple, la configuration suivante utilise le nom commun du certificat comme sujet canonique et rend l’unité organisationnelle disponible comme attribut de correspondance supplémentaire :

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

Les informations du certificat sont disponibles sous assertion.subject et assertion.subject_alt_names. Les transformations utilisées dans les règles de correspondance doivent produire des valeurs scalaires. Chaque transformation supplémentaire doit avoir un nom openai.* unique.

Par exemple, l’expression suivante dans Conditions sur les attributs permet au fournisseur de n’accepter que les certificats de production :

assertion.subject.organizational_unit == "Production"

Créer une règle de correspondance pour un compte de service

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

Par exemple :

Les règles de correspondance X.509 utilisent les attributs dérivés openai.*. Elles ne s’appliquent pas aux revendications JWT brutes telles que sub, iss ou aud.

La liste des fournisseurs affiche l’identifiant du fournisseur. Les détails de la règle de correspondance indiquent le compte de service sélectionné et son identifiant. Notez ces deux identifiants. La charge de travail les envoie lors de l’échange de jetons.

Utiliser une identité de charge de travail X.509 avec un SDK

Définissez les 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"

Dans le fichier de chaîne de certificats, placez d’abord le certificat final, puis les é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 jetons et des requêtes à l’API, dirige ces requêtes vers le point de terminaison mTLS et renouvelle automatiquement les jetons d’accès de courte durée.

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 une version du SDK OpenAI qui prend en charge la configuration X.509 présentée ici. Les versions minimales sont 7.8.0 pour JavaScript avec la dépendance paire undici installée, 3.6.0 pour Python, 3.54.0 pour Go, 4.55.0 pour Java et 0.83.0 pour Ruby.

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

Échanger le certificat manuellement

Pour examiner ou implémenter directement le protocole d’échange de jetons, présentez le certificat au point de terminaison d’échange de jetons 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

Si l’échange réussit, la réponse contient un jeton au porteur standard de courte durée :

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 réponse contient la propriété scope uniquement si la règle de correspondance du compte de service qui s’applique accorde des autorisations.

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

Si l’échange réussit, récupérez la valeur access_token dans la réponse 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.

Appeler 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 à l’API.

Aucun lien cryptographique n’associe le jeton au porteur au certificat. La configuration la plus simple consiste à réutiliser le certificat d’échange pour la requête à l’API. Vous pouvez aussi utiliser un autre certificat pour cette requête, à condition qu’il satisfasse à lui seul à la même politique mTLS en vigueur pour l’API.

Durée de validité et renouvellement des jetons

Un jeton d’identité de charge de travail X.509 expire au bout d’une heure au maximum, et au plus tard à l’expiration du certificat client vérifié. L’échange ne renvoie aucun jeton de renouvellement. Répétez l’échange du certificat pour obtenir un nouveau jeton d’accès.

Pour les échanges manuels, conservez expires_at avec le jeton d’accès et planifiez un nouvel échange avant l’instant indiqué. Tenez compte des écarts entre les horloges et de la latence des requêtes. Vous trouverez un exemple dans les instructions de renouvellement du jeton.

Le remplacement d’un certificat intermédiaire ne nécessite aucune modification de la racine configurée. Présentez la nouvelle chaîne complète lors des échanges et des requêtes à l’API qui suivent.

Résoudre les erreurs d’échange de jetons

En cas d’échec, l’échange de jetons X.509 renvoie des erreurs OAuth génériques sans fournir de détails sur le certificat, la racine, le fournisseur ou la règle de correspondance.

Un échange X.509 ne bascule jamais vers un flux OIDC ou OAuth standard.

Limites

• Les fournisseurs d’identités de charges de travail X.509 ne gèrent pas de magasin de certificats de confiance distinct.
• Le jeton au porteur n’est pas lié au certificat et n’utilise ni DPoP ni revendication cnf.
• Même après l’échange, le certificat seul ne suffit pas à autoriser un appel à l’API. Les requêtes à l’API nécessitent toujours le jeton au 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.
• Dans ce flux, OpenAI ne consulte pas les listes de révocation de certificats (CRL) et n’effectue pas de vérifications OCSP. Pour préparer votre réponse aux incidents liés aux certificats, tenez compte des contrôles disponibles sur les racines TLS mutuel, les fournisseurs et les règles de correspondance, ainsi que de la courte durée de validité des jetons émis.
• Ce flux ne prend pas en charge les X.509-SVID SPIFFE. Le guide SPIFFE utilise toujours des JWT-SVID.