如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

为 Oracle Cloud Infrastructure 配置工作负载身份联合

将 Oracle Cloud Infrastructure(OCI)用作工作负载身份提供方时,您可以使用 Oracle Identity Cloud Service(IDCS)访问令牌换取短期 OpenAI 访问令牌。OCI 实例主体对发往同一租户内身份域的令牌交换请求进行签名。OpenAI 验证返回的令牌,并授权 OCI 工作负载以映射的 OpenAI 服务账号身份执行操作。

此配置无需 OpenAI API 密钥,也无需创建自定义 Oracle OAuth 资源应用或授予动态组访问自定义应用的权限。

设置 OCI 工作负载

在具有实例主体的 OCI 计算实例上运行工作负载。如果使用 Oracle Kubernetes Engine(OKE),请确认签署请求所用的身份。标准实例主体签名器使用的身份通常对应工作节点,而非单个 Kubernetes Pod。

签名器从 OCI 实例元数据服务获取凭据。请验证工作负载能否访问链路本地元数据端点:

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

工作负载还必须能够向其所属租户中的身份域发送出站 HTTPS 请求。访问元数据端点本身无需 NAT 网关或互联网连接。

请求 Oracle 身份令牌

使用 OCI Python SDK 中的 InstancePrincipalsSecurityTokenSigner 对发往您的身份域的 OAuth 令牌交换请求进行签名:

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

urn:opc:idm:__myscopes__ 作用域使用实例主体已有的授权。将返回的 IDCS 访问令牌用作 OpenAI 工作负载身份联合的主体令牌。不要将 Oracle 令牌的受众替换为 https://api.openai.com/v1。配置 OpenAI 身份提供方时,请使用 Oracle 令牌中实际包含的受众值。

验证令牌

将 TOKEN 设置为实际运行的 OCI 工作负载生成的访问令牌,然后使用现有的本地 JWT 解码器查看令牌中的声明:

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);

解码器只查看令牌内容,不验证签名。请将原始令牌视为敏感信息,不要将其写入日志,也不要将生产环境的令牌粘贴到第三方 JWT 解码器中。

解码后的 Oracle 访问令牌可能包含以下声明:

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

请以您自己的身份域签发的令牌为准。配置时,原样填写 iss 的值,并选用令牌中的一个 aud 值。为工作负载授权时,优先使用 ipst_instance、ipst_compartment、domain_id 和 ca_ocid 这些不可变的声明。

设置工作负载身份联合

为您的 Oracle 身份域创建工作负载身份提供方,然后添加映射,指定可使用目标 OpenAI 服务账号的 OCI 实例或这些实例所在的区间。

设置工作负载身份提供方

  1. 创建工作负载身份提供方。 将名称设置为唯一值,例如 oracle-cloud-prod。在描述中注明受信任的工作负载,例如 Production OCI instance principal。

  2. 设置签发者和受众。 将 OIDC 签发者 URL 设置为令牌中 iss 声明的值,例如 https://identity.oraclecloud.com/。将受众设置为同一令牌中的一个 aud 值。

  3. 如果支持,请配置租户专属的 OIDC 发现。 如果使用自定义 URL 进行 OIDC 发现选项出现在高级设置中,请启用该选项。将自定义 OIDC 发现 URL 设置为您所在租户的身份域 URL,例如 https://idcs-example.identity.oraclecloud.com。OpenAI 会获取 https://idcs-example.identity.oraclecloud.com/.well-known/openid-configuration,然后通过发现文档中的 jwks_uri 获取该租户用于验证签名的公钥。如果没有自定义发现选项,请启用使用上传的 JWKS 验证令牌,并上传从 https://<identity-domain>/admin/v1/SigningCert/jwk 获取的公钥集。

  4. 仅在需要派生属性时添加属性转换。 您可以直接在服务账号映射断言中使用 ipst_instance、ipst_compartment、domain_id 和 ca_ocid 等 Oracle 原始声明。要显式派生实例属性,请输入属性名 instance 和表达式 assertion.ipst_instance,以创建 openai.instance。

Oracle 的 OpenID Connect 发现参考文档说明了自定义发现的重要性。发现文档可以将全局 URL https://identity.oraclecloud.com/ 声明为签发者,同时在租户专属身份域上发布令牌端点和 jwks_uri。请在 OIDC 签发者 URL 中保留全局签发者地址,并将自定义 OIDC 发现 URL 设置为租户的身份域地址。

如果您的身份域在令牌签发者地址发布发现元数据,请保持自定义发现处于禁用状态,并使用标准 OIDC 发现。如果 OpenAI 无法访问租户的发现文档或签名密钥端点,请禁用自定义发现,启用使用上传的 JWKS 验证令牌,并上传从 https://<identity-domain>/admin/v1/SigningCert/jwk 获取的租户公钥集。自定义发现和上传的 JWKS 无法同时启用。Oracle 轮换签名证书时,请更新已上传的密钥。

设置服务账号映射

  1. 创建服务账号映射。 将名称设置为唯一值,例如 oracle-instance-prod,并添加描述,注明受信任的 OCI 工作负载。

  2. 匹配范围最小且稳定的 OCI 身份。 要向单个实例授予访问权限,请将键设置为 ipst_instance,并在值中原样填写已验证令牌中的实例 OCID。要向某个区间内的实例授予访问权限,请将键设置为 ipst_compartment,并在值中原样填写该区间的 OCID。

  3. 按需限定身份域和租户范围。 为 domain_id 或 ca_ocid 添加额外的映射行,将工作负载限定在特定的 Oracle 身份域或租户中。如果令牌包含 sub_type 声明,并且您希望仅允许实例主体访问,请为该声明添加映射行,并将值设置为 instance。所有映射行都必须匹配。

  4. 选择 OpenAI 目标。 将项目设置为服务账号所属的项目,然后选择受信任的 OCI 工作负载可以使用的服务账号。

  5. 按需缩小 API 权限范围。 在权限中仅选择工作负载所需的权限。映射可以限制所选服务账号的权限,但无法授予该账号尚未拥有的权限。

使用标准实例主体签名器的 OKE 工作负载会继承工作节点的身份。实例级映射会授权整个节点,授权范围不限于单个 Pod。如果需要隔离同一工作节点上的不同 Pod,请使用 OCI 支持的、范围更小的工作负载身份。

在代码中使用令牌

安装 OpenAI、OCI 和 Requests 的 Python 包:

pip install openai oci requests

如果使用 Ruby,请安装 OpenAI 和 OCI 的 gem 包:

gem install openai oci

将 OCI_IDENTITY_DOMAIN_URL 设置为身份域的基础 URL。该身份域必须与工作负载属于同一租户。将 OPENAI_IDENTITY_PROVIDER_ID 和 OPENAI_SERVICE_ACCOUNT_ID 分别设置为您的 OpenAI 身份提供方 ID 和服务账号映射中指定的服务账号 ID。

以下示例使用 OCI 实例主体签署 Oracle 令牌交换请求,并将 IDCS 访问令牌返回给 OpenAI SDK。SDK 会在需要时使用该令牌换取短期 OpenAI 访问令牌:

使用 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-6.1-terra",
    input="Say hello from Oracle Cloud Infrastructure workload identity federation.",
)

print(response.output_text)

当 OpenAI SDK 需要续期工作负载身份凭据时,主体令牌提供方会请求新的 Oracle 令牌。切勿打印或持久化存储 Oracle 主体令牌或换取的 OpenAI 访问令牌。

OCI 安全建议

  • 如果只应允许一个工作负载访问,请使用 ipst_instance 映射单个实例。
  • 仅当某个区间中所有符合条件的实例都应共用同一映射时,才使用 ipst_compartment。
  • 添加 domain_id 或 ca_ocid,将访问范围限定在指定的身份域或租户内。
  • 为每个应用在每个环境中分别使用独立的 OpenAI 服务账号。
  • 在依赖 Pod 级隔离之前,请先确认 OKE 令牌是否代表工作节点。
  • 使用 Oracle 签发的令牌中实际包含的受众值,不要假定令牌使用 OpenAI 专属受众。
  • 如果您的身份域无法使用 OIDC 发现,请在 Oracle 轮换签名密钥时同步轮换已上传的公钥。