For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal

Configuração da federação de identidades de cargas de trabalho para Oracle Cloud Infrastructure

Use o Oracle Cloud Infrastructure (OCI) como provedor de identidade de cargas de trabalho, trocando um token de acesso do Oracle Identity Cloud Service (IDCS) por um token de acesso da OpenAI de curta duração. Um principal de instância do OCI assina uma solicitação de troca de tokens para um domínio de identidade na mesma tenancy. A OpenAI valida o token resultante e autoriza a carga de trabalho do OCI a atuar como uma conta de serviço da OpenAI mapeada.

Para o Codex, use esta página para obter e inspecionar o token da Oracle. Em seguida, configure a identidade de cargas de trabalho do Codex para gravar esse token em um arquivo e indicar ao Codex onde encontrá-lo. O mapeamento de contas de serviço e os exemplos de SDK desta página se aplicam à API da OpenAI.

Essa configuração não exige uma chave de API da OpenAI, um aplicativo de recurso OAuth personalizado da Oracle nem concessões de grupos dinâmicos a um aplicativo personalizado.

Configure a carga de trabalho do OCI

Execute sua carga de trabalho em uma instância do OCI Compute com um principal de instância. Para o Oracle Kubernetes Engine (OKE), confirme qual identidade assina a solicitação: o assinador padrão de principal de instância normalmente identifica o node de trabalho, e não um pod individual do Kubernetes.

O assinador obtém credenciais do serviço de metadados de instâncias do OCI. Verifique se a carga de trabalho consegue acessar o endpoint de metadados de link local:

curl --fail --silent \
  --header "Authorization: Bearer Oracle" \
  http://169.254.169.254/opc/v2/instance/id

A carga de trabalho também deve conseguir fazer solicitações HTTPS de saída para o domínio de identidade em sua tenancy. O endpoint de metadados em si não exige um gateway NAT nem conexão com a internet.

Solicite um token de identidade da Oracle

Use InstancePrincipalsSecurityTokenSigner do SDK do OCI para Python para assinar uma solicitação de troca de tokens OAuth para seu domínio de identidade:

POST https://<identity-domain>/oauth2/v1/token
Content-Type: application/x-www-form-urlencoded;charset=utf-8

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
scope=urn:opc:idm:__myscopes__
requested_token_type=urn:ietf:params:oauth:token-type:access_token

O escopo urn:opc:idm:__myscopes__ usa a autorização existente do principal de instância. Use o token de acesso do IDCS retornado como token de sujeito para a federação de identidades de cargas de trabalho da OpenAI. Não substitua o público-alvo do token da Oracle por https://api.openai.com/v1; configure o provedor da OpenAI com um público-alvo que conste no token real da Oracle.

Verifique o token

Defina TOKEN como um token de acesso gerado pela carga de trabalho real do OCI e, em seguida, use o decodificador JWT local existente para inspecionar suas declarações:

const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}
if (!/^[A-Za-z0-9_-]+$/.test(parts[1]) || parts[1].length % 4 === 1) {
  throw new Error("JWT payload is not valid Base64URL");
}

const bytes = Buffer.from(parts[1], "base64url");
if (bytes.toString("base64url") !== parts[1]) {
  throw new Error("JWT payload is not valid Base64URL");
}
const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
const claims = JSON.parse(decoded);
if (claims === null || Array.isArray(claims) || typeof claims !== "object") {
  throw new Error("JWT payload is not a JSON object");
}
console.log(decoded);

O decodificador inspeciona o token sem verificar sua assinatura. Trate os tokens brutos como dados sensíveis, não os registre em logs e não cole tokens de produção em decodificadores JWT de terceiros.

Um token de acesso da Oracle decodificado pode conter as seguintes declarações:

{
  "iss": "https://identity.oraclecloud.com/",
  "aud": [
    "https://idcs-example.us-phoenix-1.identity.oraclecloud.com",
    "https://idcs-example.identity.oraclecloud.com"
  ],
  "sub_type": "instance",
  "ipst_instance": "ocid1.instance.oc1.phx.<instance-id>",
  "ipst_compartment": "ocid1.compartment.oc1..<compartment-id>",
  "domain_id": "ocid1.domain.oc1..<domain-id>",
  "ca_ocid": "ocid1.tenancy.oc1..<tenancy-id>",
  "tenant": "idcs-example",
  "exp": 1782369434,
  "iat": 1782365834
}

Use o token emitido pelo seu próprio domínio de identidade como fonte de verdade. Configure o valor exato de iss e um dos valores de aud do token. Dê preferência às declarações imutáveis ipst_instance, ipst_compartment, domain_id e ca_ocid ao autorizar uma carga de trabalho.

Configure a federação de identidades de cargas de trabalho

Crie um provedor de identidade de cargas de trabalho para seu domínio de identidade da Oracle e adicione um mapeamento para a instância ou o compartimento do OCI que pode usar a conta de serviço de destino da OpenAI.

Configure o provedor de identidade de cargas de trabalho

  1. Crie o provedor de identidade de cargas de trabalho. Defina Nome como um valor exclusivo, como oracle-cloud-prod. Use Descrição, com um valor como Production OCI instance principal, para identificar a carga de trabalho confiável.

  2. Defina o emissor e o público-alvo. Defina URL do emissor OIDC como a declaração iss do token, como https://identity.oraclecloud.com/. Defina Público-alvo como um dos valores de aud no mesmo token.

  3. Configure a descoberta OIDC específica do tenant quando disponível. Se Usar URL personalizada para descoberta OIDC aparecer em Avançado, ative essa opção. Defina URL personalizada de descoberta OIDC como o domínio de identidade específico do seu tenant, como https://idcs-example.identity.oraclecloud.com. A OpenAI obtém https://idcs-example.identity.oraclecloud.com/.well-known/openid-configuration e usa o jwks_uri do documento de descoberta para obter as chaves públicas de assinatura do tenant. Se a opção de descoberta personalizada não aparecer, ative Usar JWKS enviado para verificação de tokens e, em vez disso, envie o JWKS público de https://<identity-domain>/admin/v1/SigningCert/jwk.

  4. Adicione transformações de atributos somente quando precisar de atributos derivados. Você pode usar declarações brutas da Oracle, como ipst_instance, ipst_compartment, domain_id e ca_ocid, diretamente nas asserções de mapeamento de contas de serviço. Para um atributo de instância explicitamente derivado, insira instance com a expressão assertion.ipst_instance para criar openai.instance.

A referência de descoberta do OpenID Connect da Oracle mostra por que a descoberta personalizada é importante: o documento de descoberta pode declarar o emissor global https://identity.oraclecloud.com/ e, ao mesmo tempo, publicar o endpoint de tokens e o jwks_uri no domínio de identidade específico do tenant. Mantenha o emissor global em URL do emissor OIDC e use o domínio do tenant em URL personalizada de descoberta OIDC.

Se seu domínio de identidade publicar metadados de descoberta no emissor do token, mantenha a descoberta personalizada desativada e use a descoberta OIDC padrão. Se a OpenAI não conseguir acessar o documento de descoberta do tenant ou o endpoint de chaves de assinatura, desative a descoberta personalizada, ative Usar JWKS enviado para verificação de tokens e envie o JWKS público do tenant obtido em https://<identity-domain>/admin/v1/SigningCert/jwk. A descoberta personalizada e o JWKS enviado não podem ser ativados ao mesmo tempo. Atualize as chaves enviadas quando a Oracle fizer a rotação de seus certificados de assinatura.

Configure o mapeamento de contas de serviço

  1. Crie um mapeamento de contas de serviço. Defina Nome como um valor exclusivo, como oracle-instance-prod, e adicione uma descrição que identifique a carga de trabalho confiável do OCI.

  2. Faça a correspondência com a identidade estável do OCI de escopo mais restrito. Para conceder acesso a uma instância, defina Chave como ipst_instance e Valor como o OCID exato da instância presente no token verificado. Para conceder acesso às instâncias de um compartimento, defina Chave como ipst_compartment e Valor como o OCID exato do compartimento.

  3. Adicione restrições de domínio e tenancy quando necessário. Adicione outras linhas de mapeamento para domain_id ou ca_ocid para limitar a carga de trabalho a um domínio de identidade ou a uma tenancy específica da Oracle. Adicione sub_type com o valor instance quando o token incluir essa declaração e você quiser exigir um principal de instância. Todas as linhas de mapeamento devem corresponder.

  4. Escolha o destino na OpenAI. Defina Projeto como o projeto ao qual a conta de serviço pertence e selecione a Conta de serviço que a carga de trabalho confiável do OCI pode usar.

  5. Restrinja as permissões de API se necessário. Selecione apenas as Permissões necessárias para a carga de trabalho. As permissões do mapeamento podem restringir a conta de serviço selecionada, mas não podem conceder permissões que ela ainda não tenha.

Uma carga de trabalho do OKE que usa o assinador padrão de principal de instância herda a identidade do node de trabalho. Um mapeamento no nível da instância autoriza esse node, não apenas um pod. Use uma identidade de cargas de trabalho do OCI mais específica e compatível quando precisar de isolamento entre pods que compartilham um node de trabalho.

Use o token no código

Instale os pacotes Python OpenAI, OCI e Requests:

pip install openai oci requests

Para Ruby, instale as gems OpenAI e OCI:

gem install openai oci

Defina OCI_IDENTITY_DOMAIN_URL como a URL base do domínio de identidade na mesma tenancy da carga de trabalho. Defina OPENAI_IDENTITY_PROVIDER_ID e OPENAI_SERVICE_ACCOUNT_ID como os IDs do seu provedor e do mapeamento de contas de serviço da OpenAI.

O exemplo a seguir assina uma solicitação de troca de tokens da Oracle com o principal de instância do OCI, retorna o token de acesso do IDCS ao OpenAI SDK e permite que o SDK o troque por um token de acesso da OpenAI de curta duração quando necessário:

Autentique-se com um principal de instância do OCI
import os

import oci
import requests
from openai import OpenAI
from openai.auth import SubjectTokenProvider


def oracle_instance_principal_token_provider(
    identity_domain_url: str,
) -> SubjectTokenProvider:
    def get_token() -> str:
        signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
        response = requests.post(
            f"{identity_domain_url.rstrip('/')}/oauth2/v1/token",
            data={
                "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
                "scope": "urn:opc:idm:__myscopes__",
                "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
            },
            headers={
                "Content-Type": "application/x-www-form-urlencoded;charset=utf-8",
            },
            auth=signer,
            timeout=30,
        )
        response.raise_for_status()

        token = response.json().get("access_token")
        if not isinstance(token, str) or not token:
            raise RuntimeError("Oracle IDCS did not return an access token.")

        return token

    return {"token_type": "jwt", "get_token": get_token}


client = OpenAI(
    workload_identity={
        "identity_provider_id": os.environ["OPENAI_IDENTITY_PROVIDER_ID"],
        "service_account_id": os.environ["OPENAI_SERVICE_ACCOUNT_ID"],
        "provider": oracle_instance_principal_token_provider(
            os.environ["OCI_IDENTITY_DOMAIN_URL"]
        ),
    },
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Say hello from Oracle Cloud Infrastructure workload identity federation.",
)

print(response.output_text)

O provedor de tokens de sujeito solicita um novo token da Oracle quando o OpenAI SDK precisa renovar a credencial de identidade de cargas de trabalho. Nunca imprima nem persista o token de sujeito da Oracle ou o token de acesso da OpenAI resultante.

Recomendações de segurança do OCI

  • Mapeie uma instância com ipst_instance quando apenas uma carga de trabalho deva ter acesso.
  • Use ipst_compartment somente quando todas as instâncias elegíveis desse compartimento devam compartilhar o mapeamento.
  • Adicione domain_id ou ca_ocid para aplicar restrições de domínio de identidade e tenancy.
  • Use uma conta de serviço da OpenAI separada para cada aplicativo e ambiente.
  • Verifique se um token do OKE representa um node de trabalho antes de confiar no isolamento no nível de pod.
  • Use o público-alvo presente no token emitido pela Oracle em vez de presumir um público-alvo específico da OpenAI.
  • Faça a rotação das chaves públicas enviadas quando a Oracle fizer a rotação de suas chaves de assinatura, caso seu domínio de identidade não possa usar a descoberta OIDC.