Configurar la federación de identidades de cargas de trabajo con certificados X.509

La federación de identidades de cargas de trabajo con X.509 permite que una carga de trabajo intercambie la 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. El certificado de cliente sigue siendo necesario.

Para conocer los detalles de la solicitud y la respuesta de intercambio de tokens, consulta la referencia sobre el intercambio de tokens de identidad de cargas de trabajo. Para obtener información sobre los permisos de TLS mutuo, los requisitos de los certificados, su activación y rotación, y los hosts de mTLS, consulta la guía de TLS mutuo.

Cómo funciona

El intercambio de identidades de cargas de trabajo con X.509 consta de cinco pasos:

1. Tu organización carga y activa un certificado raíz de confianza en su configuración actual de TLS mutuo.
2. Un proveedor de identidades de cargas de trabajo X.509 obtiene los atributos openai.* a partir del certificado de cliente verificado. Debe obtener un único valor no vacío para openai.subject.
3. Una asignación de cuenta de servicio autoriza a la identidad obtenida a usar una sola 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 de portador de corta duración. El certificado se obtiene de la conexión TLS. El cuerpo de la solicitud no contiene un subject_token.
5. La carga de trabajo presenta el token de portador y un certificado de cliente a una ruta de la API en mtls.api.openai.com para que la API autorice la solicitud.

La API verifica por separado la autorización del token de portador y la del certificado en cada solicitud. Un certificado por sí solo no autoriza una llamada a la API de OpenAI.

Antes de comenzar

Necesitas lo siguiente:

• Permiso para administrar los certificados de TLS mutuo y los proveedores de identidades de cargas 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 formar una cadena hasta la raíz de confianza.
• Un certificado raíz de confianza activo en la organización o el proyecto.

Mantén las claves privadas fuera del sistema de control de versiones y permite que solo la carga de trabajo que las usa tenga acceso a ellas. No registres las claves privadas, el contenido de los certificados ni los tokens de acceso devueltos.

Configurar la confianza en los certificados de TLS mutuo

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

Sigue la guía de TLS mutuo para revisar los requisitos de los certificados, los hosts de mTLS, el funcionamiento de la activación de 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 cargas de trabajo con X.509.

Si la cadena de tu certificado de cliente pasa por un certificado intermedio, configura el ancla de confianza estable. Durante la negociación TLS, presenta primero el certificado de cliente y luego los certificados intermedios vigentes. OpenAI usa los certificados intermedios que se incluyen en la solicitud y no recupera los que faltan de las URL de los certificados.

Configurar un proveedor X.509

Para configurar un proveedor X.509:

1. Abre Configuración de la organización > Seguridad > Proveedor de identidades de cargas de trabajo y selecciona Crear proveedor de identidades.
2. Elige X.509 en Tipo de proveedor y luego ingresa un nombre y, si quieres, una descripción. Los proveedores X.509 no usan las opciones de configuración de emisor, audiencia, descubrimiento ni JWKS de OIDC. Una vez creado el proveedor, no puedes cambiar su tipo.
3. En Opciones avanzadas, puedes agregar una expresión CEL en Condiciones de los atributos para rechazar certificados antes de determinar qué asignación corresponde.
4. En Transformaciones de atributos, ingresa una expresión no vacía para la transformación obligatoria openai.subject. Cuando seleccionas X.509, el panel agrega la fila subject y muestra y aplica el prefijo openai.. Elige un dato estable del certificado que identifique la carga de trabajo.
5. Si quieres, 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 permite usar la unidad organizativa como atributo adicional en las asignaciones:

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

Puedes acceder a los datos del certificado en assertion.subject y assertion.subject_alt_names. Los resultados de las transformaciones que se usan en las asignaciones deben ser valores escalares. Las transformaciones adicionales deben tener nombres openai.* únicos.

Por ejemplo, con una expresión en Condiciones de los atributos, puedes hacer que el proveedor solo acepte certificados de producción:

assertion.subject.organizational_unit == "Production"

Crear 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, especifica el valor exacto que debe tener openai.subject. Las asignaciones X.509 admiten tanto la ausencia de aserciones, representada por un objeto vacío ({}), como las aserciones cuyas claves comienzan con openai..
4. Selecciona Crear.

Por ejemplo:

Las asignaciones X.509 usan los atributos openai.* derivados del certificado. No buscan coincidencias en las declaraciones originales de un JWT, como sub, iss o aud.

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

Usar la identidad de una carga de trabajo con X.509 mediante un SDK

Configura las 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 de cliente y luego los certificados intermedios, si los hay. No incluyas datos de los 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 en las solicitudes a la API, dirige estas solicitudes al punto de acceso de 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 de los SDK de OpenAI compatibles con 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 crear su X509ExtendedKeyManager y usa el almacén de confianza predeterminado de la plataforma para crear su X509TrustManager. Para este ejemplo, configura OPENAI_X509_KEYSTORE_PATH, OPENAI_X509_KEYSTORE_PASSWORD y OPENAI_X509_CERTIFICATE_ALIAS. Como alternativa, puedes proporcionar al SDK gestores que usen archivos PEM o hardware.

Intercambiar 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

Si el intercambio tiene éxito, devuelve un token de 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 respuesta solo incluye la propiedad scope cuando la asignación de cuenta de servicio correspondiente tiene permisos.

Los valores de vencimiento son ilustrativos. La vigencia del token devuelto puede ser menor si el certificado de cliente verificado vence antes. Consulta los campos de la respuesta de intercambio de tokens para conocer las unidades y el significado de expires_in y expires_at.

Lee el valor de 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: no lo imprimas, no lo registres ni lo incluyas en un commit.

Llamar a la API de OpenAI manualmente

Asigna a OPENAI_MODEL el valor gpt-6-astra, que es el modelo predeterminado actual, o el de otro modelo disponible para el proyecto de destino. Luego, envía el token de portador y un certificado de cliente aceptado al punto de acceso de 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 de portador en lugar de una clave de API y sigue presentando un certificado de cliente aceptado en la solicitud a la API.

El token de portador no está vinculado criptográficamente al certificado. La configuración más sencilla consiste en reutilizar el certificado del intercambio en la solicitud a la API. También puedes usar otro certificado en la solicitud si cumple por sí mismo la misma política de mTLS vigente para la API.

Vigencia y renovación del token

Un token de identidad de carga de trabajo X.509 tiene una vigencia máxima de una hora y nunca vence después del certificado de cliente verificado. El intercambio no devuelve un token de actualización. Repite el intercambio del certificado para obtener otro token de acceso.

Si haces el intercambio manualmente, guarda expires_at junto con el token de acceso y programa otro intercambio antes de la hora indicada. Deja margen para las diferencias entre los relojes y la latencia de la solicitud. Consulta las instrucciones para renovar el token para ver un ejemplo.

Si rotas un certificado intermedio, no necesitas cambiar la raíz configurada. Presenta la nueva cadena completa en los intercambios y las solicitudes a la API posteriores.

Solucionar problemas de intercambio de tokens

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

Si un intercambio X.509 falla, nunca se recurre a un flujo OIDC ni a un flujo OAuth convencional.

Limitaciones

• Los proveedores de identidades de cargas de trabajo X.509 no mantienen un almacén de certificados de confianza independiente.
• El token de portador no está vinculado al certificado y no usa DPoP ni una declaración cnf.
• El intercambio del certificado no basta para autorizar una solicitud a la API. Las solicitudes a la API siguen requiriendo el token de portador y un certificado de cliente aceptado.
• OpenAI no recupera de las URL de AIA los certificados intermedios que faltan. Presenta la cadena completa durante la negociación TLS.
• Durante este flujo, OpenAI no consulta listas de revocación de certificados (CRL) ni realiza comprobaciones mediante OCSP. Al planificar la respuesta a incidentes con certificados, ten en cuenta los controles sobre las raíces de TLS mutuo, los proveedores y las asignaciones, así como la corta vigencia de los tokens emitidos.
• Este flujo no agrega compatibilidad con los X.509-SVID de SPIFFE. La guía de SPIFFE sigue usando JWT-SVID.