Configure a federação de identidades de cargas de trabalho com certificados X.509

A federação de identidades de cargas de trabalho X.509 permite que uma carga de trabalho troque a identidade de um certificado de cliente TLS por um token de acesso da OpenAI de curta duração. Em seguida, a carga de trabalho chama a API da OpenAI usando tanto o token de acesso quanto um certificado de cliente aceito. Esse fluxo substitui a chave de API, não o certificado de cliente.

Para ver detalhes das requisições e respostas de troca de tokens, consulte a referência de troca de tokens de identidade de cargas de trabalho. Para saber mais sobre permissões de TLS mútuo, requisitos de certificados, ativação, hosts mTLS e rotação, consulte o guia de TLS mútuo.

Como funciona

Uma troca de identidade de cargas de trabalho X.509 tem cinco partes:

1. Sua organização envia e ativa um certificado raiz confiável nas configurações existentes de TLS mútuo.
2. Um provedor de identidade de cargas de trabalho X.509 deriva atributos openai.* do certificado de cliente verificado. Ele deve derivar um valor não vazio de openai.subject.
3. Um mapeamento de conta de serviço autoriza a identidade derivada a usar uma conta de serviço da OpenAI em um projeto.
4. A carga de trabalho apresenta seu certificado ao endpoint de tokens X.509 em mtls.auth.openai.com e solicita um token bearer de curta duração. O certificado vem da conexão TLS; o corpo da requisição não contém um subject_token.
5. A carga de trabalho apresenta o token bearer e um certificado de cliente a uma rota da API em mtls.api.openai.com para obter autorização na API.

O token bearer e o certificado são autorizados de forma independente na requisição à API. Um certificado, por si só, não autoriza uma chamada à API da OpenAI.

Antes de começar

Você precisa de:

• Permissão para gerenciar certificados de TLS mútuo e provedores de identidade de cargas de trabalho da sua organização.
• Um projeto e uma conta de serviço para a carga de trabalho.
• Um certificado de cliente, sua chave privada e todos os certificados intermediários necessários para formar uma cadeia até a raiz confiável.
• Um certificado raiz confiável ativo no nível da organização ou do projeto.

Mantenha as chaves privadas fora do controle de versão e restrinja o acesso a elas à carga de trabalho que as utiliza. Não registre em logs chaves privadas, o conteúdo de certificados nem os tokens de acesso retornados.

Configure a confiança em certificados de TLS mútuo

Os provedores de identidade de cargas de trabalho X.509 reutilizam a configuração existente de certificados de TLS mútuo da sua organização. Eles não enviam certificados nem mantêm um repositório separado de certificados confiáveis.

Siga o guia de TLS mútuo para revisar os requisitos de certificados, os hosts mTLS, o comportamento de ativação de certificados, os filtros CEL e a configuração do cliente. Em seguida, abra Configurações da organização > Segurança > TLS mútuo, envie o certificado confiável no formato PEM e ative-o para a organização ou para cada projeto que usará a federação de identidades de cargas de trabalho X.509.

Se a cadeia do seu certificado de cliente passar por um certificado intermediário, configure a âncora de confiança estável e apresente o certificado folha seguido dos certificados intermediários atuais durante o handshake TLS. A OpenAI usa os certificados intermediários fornecidos pela requisição e não busca os que estiverem faltando nas URLs dos certificados.

Configure um provedor X.509

Para configurar um provedor X.509:

1. Abra Configurações da organização > Segurança > Provedor de identidade de cargas de trabalho e selecione Criar provedor de identidade.
2. Escolha X.509 em Tipo de provedor e insira um nome e uma descrição opcional. Provedores X.509 não usam configurações de emissor, público-alvo, descoberta ou JWKS do OIDC. Não é possível alterar o tipo do provedor depois de criá-lo.
3. Em Avançado, você pode adicionar uma expressão CEL em Condições de atributos para rejeitar certificados antes da resolução do mapeamento.
4. Em Transformações de atributos, insira uma expressão não vazia para a transformação obrigatória openai.subject. O painel adiciona a linha subject quando você seleciona X.509, além de exibir e aplicar o prefixo openai.. Escolha um dado estável do certificado que identifique a carga de trabalho.
5. Se quiser, adicione transformações com outros nomes openai.* exclusivos e selecione Criar.

Por exemplo, esta configuração usa o nome comum do certificado como sujeito canônico e disponibiliza a unidade organizacional como um atributo adicional de mapeamento:

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

Os dados do certificado estão disponíveis em assertion.subject e assertion.subject_alt_names. Os resultados das transformações usados em mapeamentos devem ser valores escalares. Transformações adicionais devem ter nomes openai.* exclusivos.

Por exemplo, uma expressão em Condições de atributos pode restringir o provedor a certificados de produção:

assertion.subject.organizational_unit == "Production"

Crie um mapeamento de conta de serviço

1. Na página de detalhes do provedor X.509, selecione Criar mapeamento.
2. Selecione o projeto e a conta de serviço de destino e conceda apenas as permissões de API necessárias para a carga de trabalho.
3. Nos campos Chave e Valor , exija um valor exato de openai.subject. Os mapeamentos X.509 aceitam tanto a ausência de asserções, representada por um objeto vazio ({}), quanto asserções cujas chaves começam com openai..
4. Selecione Criar.

Por exemplo:

Os mapeamentos X.509 usam atributos openai.* derivados. Eles não fazem correspondência com declarações JWT brutas, como sub, iss ou aud.

A lista de provedores exibe o ID do provedor, e os detalhes do mapeamento exibem a conta de serviço selecionada e seu ID. Anote os dois identificadores; a carga de trabalho os envia durante a troca de tokens.

Use a identidade de cargas de trabalho X.509 com um SDK

Defina as variáveis do ambiente para a cadeia de certificados, a chave privada, o provedor e a conta de serviço:

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"

O arquivo da cadeia de certificados deve conter primeiro o certificado folha, seguido dos certificados intermediários, se houver. Não inclua dados de certificados nem um subject_token no corpo da requisição.

Configure um cliente do OpenAI SDK com esses valores. O SDK apresenta o certificado de cliente durante a troca de tokens e nas requisições à API, encaminha as requisições à API para o endpoint mTLS e renova automaticamente os tokens de acesso de curta duração.

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

Estes exemplos exigem versões do OpenAI SDK que ofereçam suporte à configuração X.509 mostrada aqui: JavaScript 7.8.0 ou posterior com a dependência de par undici instalada, Python 3.6.0 ou posterior, Go 3.54.0 ou posterior, Java 4.55.0 ou posterior e Ruby 0.83.0 ou posterior.

O exemplo em Java carrega um repositório de chaves PKCS12 para construir seu X509ExtendedKeyManager e usa o repositório de certificados confiáveis padrão da plataforma para construir seu X509TrustManager. Defina OPENAI_X509_KEYSTORE_PATH, OPENAI_X509_KEYSTORE_PASSWORD e OPENAI_X509_CERTIFICATE_ALIAS para este exemplo. Como alternativa, você pode fornecer ao SDK gerenciadores baseados em PEM ou em hardware.

Troque o certificado manualmente

Para inspecionar ou implementar diretamente o protocolo de troca de tokens, apresente o certificado ao endpoint 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

Uma troca bem-sucedida retorna um token bearer comum de curta duração:

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"
}

A propriedade scope é retornada somente quando o mapeamento de conta de serviço correspondente tem permissões.

Os valores de expiração são ilustrativos. O prazo de validade retornado pode ser menor quando o certificado de cliente verificado expira antes. Consulte os campos da resposta de troca de tokens para saber as unidades e o significado de expires_in e expires_at.

Leia o valor de access_token da resposta bem-sucedida e armazene-o no repositório de credenciais da sua aplicação ou em uma variável do ambiente, como OPENAI_WIF_ACCESS_TOKEN. Trate-o como um segredo e não o exiba, registre em logs nem inclua em commits.

Chame a API da OpenAI manualmente

Defina OPENAI_MODEL como gpt-6-astra, o modelo padrão atual, ou como outro modelo disponível para o projeto de destino. Em seguida, envie o token bearer e um certificado de cliente aceito ao endpoint mTLS da 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"

Use o token bearer em vez de uma chave de API e continue apresentando um certificado de cliente aceito na requisição à API.

O token bearer não é vinculado criptograficamente ao certificado. Reutilizar o certificado da troca na requisição à API é a configuração mais direta, mas a requisição à API pode usar outro certificado que atenda, de forma independente, à mesma política mTLS vigente da API.

Validade e renovação do token

Um token de identidade de cargas de trabalho X.509 expira em, no máximo, uma hora e nunca permanece válido após a expiração do certificado de cliente verificado. A troca não retorna um token de atualização. Repita a troca de certificado para obter outro token de acesso.

Para trocas manuais, armazene expires_at junto com o token de acesso e agende outra troca antes do horário indicado por esse valor. Deixe uma margem para diferenças entre os relógios e para a latência das requisições. Consulte as orientações sobre renovação de tokens para ver um exemplo.

A rotação de um certificado intermediário não exige alterar o certificado raiz configurado. Apresente a nova cadeia completa nas próximas trocas e requisições à API.

Solucionar problemas na troca de tokens

A troca de tokens X.509 retorna erros OAuth genéricos e não expõe detalhes do certificado, do certificado raiz, do provedor ou do mapeamento.

Uma troca X.509 nunca recorre a um fluxo OIDC ou OAuth comum como alternativa.

Limitações

• Os provedores de identidade de cargas de trabalho X.509 não mantêm um repositório separado de certificados confiáveis.
• O token de portador não está vinculado ao certificado e não usa DPoP nem uma declaração cnf.
• A troca de certificado não autoriza o acesso à API apenas com o certificado. As requisições à API continuam exigindo o token de portador e um certificado de cliente aceito.
• A OpenAI não busca certificados intermediários ausentes em URLs AIA. Apresente a cadeia completa durante a negociação TLS.
• A OpenAI não realiza verificações de lista de revogação de certificados (CRL) ou OCSP durante esse fluxo. Planeje a resposta a incidentes com certificados com base nos controles de certificados raiz de TLS mútuo, de provedores e de mapeamentos, além do curto prazo de validade dos tokens emitidos.
• Esse fluxo não adiciona suporte a X.509-SVIDs do SPIFFE. O guia do SPIFFE continua usando JWT-SVIDs.