Configura la federación de identidades de carga de trabajo con certificados X.509

La federación de identidades de carga de trabajo X.509 permite que una carga de trabajo intercambie una identidad de un certificado de cliente TLS por un token de acceso de OpenAI de corta duración. Luego, la carga de trabajo llama a la API de OpenAI con el token de acceso y un certificado de cliente aceptado. Este flujo reemplaza la clave de API, no el certificado de cliente.

Para conocer los detalles de las solicitudes y respuestas de intercambio de tokens, consulta la referencia de intercambio de tokens de identidad de carga de trabajo. Para obtener información sobre los permisos de TLS mutuo, los requisitos de los certificados, la activación, los hosts mTLS y la rotación, consulta la guía de TLS mutuo.

Cómo funciona

Un intercambio de identidad de carga de trabajo X.509 consta de cinco partes:

1. Tu organización carga y activa un certificado raíz de confianza en su configuración existente de TLS mutuo.
2. Un proveedor de identidades de carga de trabajo X.509 deriva atributos openai.* del certificado de cliente verificado. Debe derivar un valor openai.subject que no esté vacío.
3. Una asignación de cuenta de servicio autoriza a la identidad derivada a usar una cuenta de servicio de OpenAI dentro de un proyecto.
4. La carga de trabajo presenta su certificado al punto de acceso de tokens X.509 en mtls.auth.openai.com y solicita un token al portador de corta duración. El certificado proviene de la conexión TLS; el cuerpo de la solicitud no contiene un subject_token.
5. La carga de trabajo presenta el token al portador y un certificado de cliente a una ruta de API en mtls.api.openai.com para obtener autorización para la API.

El token al portador y el certificado se autorizan de forma independiente en la solicitud a la API. Un certificado por sí solo no autoriza una llamada a la API de OpenAI.

Antes de comenzar

Necesitas:

• Permiso para administrar los certificados de TLS mutuo y los proveedores de identidades de carga de trabajo de tu organización.
• Un proyecto y una cuenta de servicio para la carga de trabajo.
• Un certificado de cliente, su clave privada y los certificados intermedios necesarios para construir una ruta hasta tu certificado raíz de confianza.
• Un certificado raíz de confianza activo a nivel de organización o de proyecto.

Mantén las claves privadas fuera del control de versiones y limita su acceso a la carga de trabajo que las utiliza. No guardes en los registros claves privadas, el contenido de los certificados ni los tokens de acceso devueltos.

Configura la confianza de los certificados de TLS mutuo

Los proveedores de identidades de carga de trabajo X.509 reutilizan la configuración existente de certificados de TLS mutuo de tu organización. No cargan certificados ni mantienen un almacén de confianza de certificados independiente.

Sigue la guía de TLS mutuo para revisar los requisitos de los certificados, los hosts mTLS, el comportamiento de activación de los certificados, los filtros CEL y la configuración del cliente. Luego, abre Configuración de la organización > Seguridad > TLS mutuo, carga el certificado de confianza en formato PEM y actívalo para la organización o para cada proyecto que vaya a usar la federación de identidades de carga de trabajo X.509.

Si la cadena de tu certificado de cliente pasa por un certificado intermedio, configura el ancla de confianza estable y presenta el certificado hoja seguido de los certificados intermedios actuales durante la negociación TLS. OpenAI usa los certificados intermedios proporcionados en la solicitud y no recupera los que falten desde las URL de los certificados.

Configura un proveedor X.509

Para configurar un proveedor X.509:

1. Abre Configuración de la organización > Seguridad > Proveedor de identidades de carga de trabajo y luego selecciona Crear proveedor de identidades.
2. Elige X.509 en Tipo de proveedor y luego ingresa un nombre y una descripción opcional. Los proveedores X.509 no usan la configuración de emisor, audiencia, descubrimiento ni JWKS de OIDC. No puedes cambiar el tipo de proveedor después de crearlo.
3. En Avanzado, puedes agregar una expresión CEL en Condiciones de atributos para rechazar certificados antes de resolver la asignación.
4. En Transformaciones de atributos, ingresa una expresión que no esté vacía para la transformación obligatoria openai.subject. El panel agrega la fila subject cuando seleccionas X.509, y muestra y aplica el prefijo openai.. Elige un dato estable del certificado que identifique la carga de trabajo.
5. Si lo deseas, agrega transformaciones con otros nombres openai.* únicos y luego selecciona Crear.

Por ejemplo, esta configuración usa el nombre común del certificado como sujeto canónico y expone la unidad organizativa como un atributo adicional de asignación:

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

Los datos del certificado están disponibles en assertion.subject y assertion.subject_alt_names. Los resultados de las transformaciones que se usan para las asignaciones deben ser valores escalares. Las transformaciones adicionales deben tener nombres openai.* únicos.

Por ejemplo, una expresión en Condiciones de atributos puede limitar el proveedor a certificados de producción:

assertion.subject.organizational_unit == "Production"

Crea una asignación de cuenta de servicio

1. En la página de detalles del proveedor X.509, selecciona Crear asignación.
2. Selecciona el proyecto y la cuenta de servicio de destino, y otorga solo los permisos de API que necesita la carga de trabajo.
3. En los campos Clave y Valor , exige un valor exacto de openai.subject. Las asignaciones X.509 admiten la ausencia de aserciones, representada como un objeto vacío ({}), o aserciones cuyas claves comiencen con openai..
4. Selecciona Crear.

Por ejemplo:

Las asignaciones X.509 usan atributos openai.* derivados. No comparan directamente las declaraciones JWT sin procesar, como sub, iss o aud.

La lista de proveedores muestra el ID del proveedor, y los detalles de la asignación muestran la cuenta de servicio seleccionada y su ID. Guarda ambos identificadores; la carga de trabajo los envía durante el intercambio de tokens.

Usa la identidad de carga de trabajo X.509 con un SDK

Establece variables de entorno para la cadena de certificados, la clave privada, el proveedor y la cuenta de servicio:

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"

El archivo de la cadena de certificados debe contener primero el certificado hoja, seguido de los certificados intermedios. No incluyas material de certificados ni un subject_token en el cuerpo de la solicitud.

Configura un cliente del SDK de OpenAI con estos valores. El SDK presenta el certificado de cliente durante el intercambio de tokens y las solicitudes a la API, dirige las solicitudes a la API al punto de acceso mTLS y renueva automáticamente los tokens de acceso de corta duración.

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

Estos ejemplos requieren versiones del SDK de OpenAI que admitan la configuración X.509 que se muestra aquí: JavaScript 7.8.0 o posterior con la dependencia par undici instalada, Python 3.6.0 o posterior, Go 3.54.0 o posterior, Java 4.55.0 o posterior y Ruby 0.83.0 o posterior.

El ejemplo de Java carga un almacén de claves PKCS12 para construir su X509ExtendedKeyManager y usa el almacén de confianza predeterminado de la plataforma para construir su X509TrustManager. Establece OPENAI_X509_KEYSTORE_PATH, OPENAI_X509_KEYSTORE_PASSWORD y OPENAI_X509_CERTIFICATE_ALIAS para este ejemplo. Como alternativa, puedes proporcionar al SDK administradores basados en PEM o respaldados por hardware.

Intercambia el certificado manualmente

Para inspeccionar o implementar directamente el protocolo de intercambio de tokens, presenta el certificado al punto de acceso 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 intercambio exitoso devuelve un token al portador estándar de corta duración:

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 propiedad scope se devuelve solo cuando la asignación de cuenta de servicio coincidente tiene permisos.

Los valores de vencimiento se muestran a modo de ejemplo. El período de validez indicado en la respuesta puede ser menor si el certificado de cliente verificado vence antes. Consulta los campos de la respuesta del intercambio de tokens para conocer las unidades y el significado de expires_in y expires_at.

Lee el valor access_token de la respuesta exitosa y guárdalo en el almacén de credenciales de tu aplicación o en una variable de entorno como OPENAI_WIF_ACCESS_TOKEN. Trátalo como un secreto y no lo imprimas, lo guardes en registros ni lo incluyas en un commit.

Llama a la API de OpenAI manualmente

Establece OPENAI_MODEL en gpt-6-astra, el modelo predeterminado actual, o en otro modelo disponible para el proyecto de destino. Luego, envía el token al portador y un certificado de cliente aceptado al punto de acceso mTLS de la 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"

Usa el token al portador en lugar de una clave de API y sigue presentando un certificado de cliente aceptado en la solicitud a la API.

El token al portador no está vinculado criptográficamente al certificado. Reutilizar el certificado del intercambio para la solicitud a la API es la configuración más directa, pero la solicitud a la API puede usar otro certificado que cumpla de forma independiente con la misma política mTLS vigente de la API.

Vigencia y renovación del token

Un token de identidad de carga de trabajo X.509 vence como máximo al cabo de una hora y nunca sigue vigente después de que vence el certificado de cliente verificado. El intercambio no devuelve un token de actualización. Repite el intercambio de certificados para obtener otro token de acceso.

Para los intercambios manuales, guarda expires_at junto con el token de acceso y programa otro intercambio antes del momento indicado por esa marca de tiempo. Ten en cuenta las diferencias entre relojes y la latencia de las solicitudes. Consulta la guía de renovación de tokens para ver un ejemplo.

La rotación de un certificado intermedio no requiere cambiar el certificado raíz configurado. Presenta la nueva cadena completa en los intercambios y las solicitudes a la API posteriores.

Solucionar problemas del intercambio de tokens

El intercambio de tokens X.509 devuelve errores genéricos de OAuth y no revela detalles del certificado, el certificado raíz, el proveedor ni la asignación.

Un intercambio X.509 nunca recurre a un flujo OIDC ni a un flujo OAuth convencional como alternativa.

Limitaciones

• Los proveedores de identidad de carga de trabajo X.509 no mantienen un almacén de confianza de certificados independiente.
• El token de portador no está vinculado al certificado y no usa DPoP ni una declaración cnf.
• El intercambio de certificados no constituye una autorización para la API basada únicamente en certificados. Las solicitudes a la API siguen requiriendo el token de portador y un certificado de cliente aceptado.
• OpenAI no obtiene los certificados intermedios faltantes desde las URL de AIA. Presenta la cadena completa durante la negociación TLS.
• OpenAI no realiza comprobaciones de listas de revocación de certificados (CRL) ni de OCSP durante este flujo. Planifica la respuesta a incidentes relacionados con certificados en función de los controles de certificados raíz de TLS mutuo, proveedores y asignaciones, y de la corta vigencia de los tokens emitidos.
• Este flujo no agrega compatibilidad con los X.509-SVIDs de SPIFFE. La guía de SPIFFE sigue usando JWT-SVIDs.