将 Oracle Cloud Infrastructure(OCI)用作工作负载身份提供方时,您可以使用 Oracle Identity Cloud Service(IDCS)访问令牌换取短期 OpenAI 访问令牌。OCI 实例主体对发往同一租户内身份域的令牌交换请求进行签名。OpenAI 验证返回的令牌,并授权 OCI 工作负载以映射的 OpenAI 服务账号身份执行操作。
此配置无需 OpenAI API 密钥,也无需创建自定义 Oracle OAuth 资源应用或授予动态组访问自定义应用的权限。
在具有实例主体的 OCI 计算实例上运行工作负载。如果使用 Oracle Kubernetes Engine(OKE),请确认签署请求所用的身份。标准实例主体签名器使用的身份通常对应工作节点,而非单个 Kubernetes Pod。
签名器从 OCI 实例元数据服务获取凭据。请验证工作负载能否访问链路本地元数据端点:
123curl --fail --silent \
--header "Authorization: Bearer Oracle" \
http://169.254.169.254/opc/v2/instance/id
工作负载还必须能够向其所属租户中的身份域发送出站 HTTPS 请求。访问元数据端点本身无需 NAT 网关或互联网连接。
使用 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 解码器查看令牌中的声明:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18const 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);
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 base64
import json
import os
import re
def reject_non_json_constant(value):
raise ValueError(f"JWT payload contains non-JSON constant: {value}")
parts = os.environ.get("TOKEN", "").split(".")
if len(parts) != 3:
raise ValueError("Expected a compact JWT with three segments")
payload = parts[1]
if re.fullmatch(r"[A-Za-z0-9_-]+", payload) is None or len(payload) % 4 == 1:
raise ValueError("JWT payload is not valid Base64URL")
padded_payload = payload + "=" * (-len(payload) % 4)
decoded = base64.b64decode(padded_payload, altchars=b"-_", validate=True)
if base64.urlsafe_b64encode(decoded).rstrip(b"=").decode("ascii") != payload:
raise ValueError("JWT payload is not valid Base64URL")
decoded_text = decoded.decode("utf-8")
claims = json.loads(decoded_text, parse_constant=reject_non_json_constant)
if not isinstance(claims, dict):
raise ValueError("JWT payload is not a JSON object")
print(decoded_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
56
57
58
59
60
61
62
63
64
65
66
67
68
69package main
import (
"bytes"
"encoding/base64"
"encoding/json"
"fmt"
"os"
"strings"
"unicode/utf8"
)
func decodeSegment(segment string) (json.RawMessage, error) {
if !isBase64URLSegment(segment) {
return nil, fmt.Errorf("JWT segment is not valid Base64URL")
}
decoded, err := base64.RawURLEncoding.DecodeString(segment)
if err != nil {
return nil, err
}
if base64.RawURLEncoding.EncodeToString(decoded) != segment {
return nil, fmt.Errorf("JWT segment is not valid Base64URL")
}
if !utf8.Valid(decoded) {
return nil, fmt.Errorf("JWT segment is not valid UTF-8")
}
var value json.RawMessage
if err := json.Unmarshal(decoded, &value); err != nil {
return nil, err
}
if trimmed := bytes.TrimSpace(value); len(trimmed) == 0 || trimmed[0] != '{' {
return nil, fmt.Errorf("JWT segment is not a JSON object")
}
return value, nil
}
func isBase64URLSegment(segment string) bool {
if segment == "" || len(segment)%4 == 1 {
return false
}
for _, character := range segment {
if !('A' <= character && character <= 'Z') &&
!('a' <= character && character <= 'z') &&
!('0' <= character && character <= '9') &&
character != '-' &&
character != '_' {
return false
}
}
return true
}
func main() {
parts := strings.Split(os.Getenv("TOKEN"), ".")
if len(parts) != 3 {
panic("Expected a compact JWT with three segments")
}
payload, err := decodeSegment(parts[1])
if err != nil {
panic(err)
}
formatted, err := json.MarshalIndent(payload, "", " ")
if err != nil {
panic(err)
}
fmt.Println(string(formatted))
}
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
77// Add Jackson (com.fasterxml.jackson.core:jackson-databind) to your project.
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.charset.CharacterCodingException;
import java.nio.charset.CodingErrorAction;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
public final class DecodeJwtPayloadExample {
private static final ObjectMapper JSON =
new ObjectMapper().enable(DeserializationFeature.FAIL_ON_TRAILING_TOKENS);
private DecodeJwtPayloadExample() {}
static String decodeUtf8(byte[] bytes) throws IOException {
try {
return StandardCharsets.UTF_8
.newDecoder()
.onMalformedInput(CodingErrorAction.REPORT)
.onUnmappableCharacter(CodingErrorAction.REPORT)
.decode(ByteBuffer.wrap(bytes))
.toString();
} catch (CharacterCodingException exception) {
throw new IOException("JWT segment is not valid UTF-8", exception);
}
}
static String decodeSegment(String segment) throws IOException {
if (!isBase64UrlSegment(segment)) {
throw new IllegalArgumentException("JWT segment is not valid Base64URL");
}
byte[] bytes = Base64.getUrlDecoder().decode(segment);
if (!Base64.getUrlEncoder().withoutPadding().encodeToString(bytes).equals(segment)) {
throw new IllegalArgumentException("JWT segment is not valid Base64URL");
}
String decoded = decodeUtf8(bytes);
JsonNode value = JSON.readTree(decoded);
if (value == null || value.isMissingNode() || !value.isObject()) {
throw new IOException("JWT segment is not a JSON object");
}
return decoded;
}
static boolean isBase64UrlSegment(String segment) {
if (segment.isEmpty() || segment.length() % 4 == 1) {
return false;
}
return segment
.chars()
.allMatch(
character ->
character >= 'A' && character <= 'Z'
|| character >= 'a' && character <= 'z'
|| character >= '0' && character <= '9'
|| character == '-'
|| character == '_');
}
static String[] requireCompactJwt(String token) {
if (token == null) {
throw new IllegalArgumentException("Expected a compact JWT with three segments");
}
String[] parts = token.split("\\.", -1);
if (parts.length != 3) {
throw new IllegalArgumentException("Expected a compact JWT with three segments");
}
return parts;
}
public static void main(String[] args) throws IOException {
String[] parts = requireCompactJwt(System.getenv("TOKEN"));
System.out.println(decodeSegment(parts[1]));
}
}
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
59using System.Text;
using System.Text.Json;
static string DecodeSegment(string segment)
{
if (
segment.Length % 4 == 1 ||
segment.Any(
character =>
!(
character is >= 'A' and <= 'Z' ||
character is >= 'a' and <= 'z' ||
character is >= '0' and <= '9' ||
character is '-' or '_'
)
)
)
{
throw new FormatException("JWT segment is not valid Base64URL");
}
byte[] decoded = Convert.FromBase64String(
segment.Replace('-', '+').Replace('_', '/') +
new string('=', (4 - segment.Length % 4) % 4)
);
string canonicalSegment = Convert
.ToBase64String(decoded)
.TrimEnd('=')
.Replace('+', '-')
.Replace('/', '_');
if (canonicalSegment != segment)
{
throw new FormatException("JWT segment is not valid Base64URL");
}
string decodedJson = new UTF8Encoding(false, true).GetString(decoded);
using JsonDocument document = JsonDocument.Parse(decodedJson);
if (document.RootElement.ValueKind is not JsonValueKind.Object)
{
throw new FormatException("JWT segment is not a JSON object");
}
return decodedJson;
}
string? token = Environment.GetEnvironmentVariable("TOKEN");
if (token is null)
{
throw new InvalidOperationException(
"Expected a compact JWT with three segments"
);
}
string[] parts = token.Split('.');
if (parts.Length != 3)
{
throw new InvalidOperationException(
"Expected a compact JWT with three segments"
);
}
Console.WriteLine(DecodeSegment(parts[1]));
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
26require "base64"
require "json"
parts = ENV.fetch("TOKEN", "").split(".", -1)
raise "Expected a compact JWT with three segments" unless parts.length == 3
unless parts[1].match?(/\A[A-Za-z0-9_-]+\z/) && parts[1].length % 4 != 1
raise "JWT payload is not valid Base64URL"
end
begin
payload = Base64.urlsafe_decode64(parts[1].ljust((parts[1].length + 3) & ~3, "="))
rescue ArgumentError
raise "JWT payload is not valid Base64URL"
end
unless Base64.urlsafe_encode64(payload, padding: false) == parts[1]
raise "JWT payload is not valid Base64URL"
end
payload.force_encoding(Encoding::UTF_8)
raise "JWT payload is not valid UTF-8" unless payload.valid_encoding?
claims = JSON.parse(payload)
raise "JWT payload is not a JSON object" unless claims.is_a?(Hash)
puts(payload)
解码器只查看令牌内容,不验证签名。请将原始令牌视为敏感信息,不要将其写入日志,也不要将生产环境的令牌粘贴到第三方 JWT 解码器中。
解码后的 Oracle 访问令牌可能包含以下声明:
123456789101112131415{
"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 实例或这些实例所在的区间。
-
创建工作负载身份提供方。 将名称设置为唯一值,例如 oracle-cloud-prod。在描述中注明受信任的工作负载,例如 Production OCI instance principal。
-
设置签发者和受众。 将 OIDC 签发者 URL 设置为令牌中 iss 声明的值,例如 https://identity.oraclecloud.com/。将受众设置为同一令牌中的一个 aud 值。
-
如果支持,请配置租户专属的 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 获取的公钥集。
-
仅在需要派生属性时添加属性转换。 您可以直接在服务账号映射断言中使用 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 轮换签名证书时,请更新已上传的密钥。
-
创建服务账号映射。 将名称设置为唯一值,例如 oracle-instance-prod,并添加描述,注明受信任的 OCI 工作负载。
-
匹配范围最小且稳定的 OCI 身份。 要向单个实例授予访问权限,请将键设置为 ipst_instance,并在值中原样填写已验证令牌中的实例 OCID。要向某个区间内的实例授予访问权限,请将键设置为 ipst_compartment,并在值中原样填写该区间的 OCID。
-
按需限定身份域和租户范围。 为 domain_id 或 ca_ocid 添加额外的映射行,将工作负载限定在特定的 Oracle 身份域或租户中。如果令牌包含 sub_type 声明,并且您希望仅允许实例主体访问,请为该声明添加映射行,并将值设置为 instance。所有映射行都必须匹配。
-
选择 OpenAI 目标。 将项目设置为服务账号所属的项目,然后选择受信任的 OCI 工作负载可以使用的服务账号。
-
按需缩小 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 访问令牌:
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
53import 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)
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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105require "json"
require "net/http"
require "oci"
require "openai"
require "uri"
class OracleInstancePrincipalTokenProvider
include OpenAI::Auth::SubjectTokenProvider
def initialize(identity_domain_url:)
@identity_domain_url = identity_domain_url.sub(%r{/+\z}, "")
end
def token_type
OpenAI::Auth::TokenType::JWT
end
def get_token
uri = URI("#{@identity_domain_url}/oauth2/v1/token")
unless uri.is_a?(URI::HTTPS)
raise OpenAI::Errors::SubjectTokenProviderError.new(
message: "Oracle identity domain URL must use HTTPS",
provider: "oracle-instance-principal"
)
end
body = URI.encode_www_form(
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"
}
signer = OCI::Auth::Signers::InstancePrincipalsSecurityTokenSigner.new
signer.sign(:post, uri.to_s, headers, body)
request = Net::HTTP::Post.new(uri)
headers.each { |name, value| request[name.to_s] = value }
request.body = body
response = Net::HTTP.start(
uri.hostname,
uri.port,
use_ssl: true,
open_timeout: 10,
read_timeout: 30
) do |http|
http.request(request)
end
unless response.is_a?(Net::HTTPSuccess)
raise OpenAI::Errors::SubjectTokenProviderError.new(
message: "Oracle identity token request failed with status #{response.code}",
provider: "oracle-instance-principal"
)
end
token = JSON.parse(response.body).fetch("access_token")
unless token.is_a?(String) && !token.empty?
raise OpenAI::Errors::SubjectTokenProviderError.new(
message: "Oracle identity domain did not return an access token",
provider: "oracle-instance-principal"
)
end
token
rescue JSON::ParserError
raise OpenAI::Errors::SubjectTokenProviderError.new(
message: "Oracle identity token response was not valid JSON",
provider: "oracle-instance-principal"
), cause: nil
rescue KeyError
raise OpenAI::Errors::SubjectTokenProviderError.new(
message: "Oracle identity domain did not return an access token",
provider: "oracle-instance-principal"
), cause: nil
rescue SystemCallError, Timeout::Error => error
raise OpenAI::Errors::SubjectTokenProviderError.new(
message: "Failed to request Oracle identity token: #{error.message}",
provider: "oracle-instance-principal",
cause: error
)
end
end
provider = OracleInstancePrincipalTokenProvider.new(
identity_domain_url: ENV.fetch("OCI_IDENTITY_DOMAIN_URL")
)
workload_identity = OpenAI::Auth::WorkloadIdentity.new(
identity_provider_id: ENV.fetch("OPENAI_IDENTITY_PROVIDER_ID"),
service_account_id: ENV.fetch("OPENAI_SERVICE_ACCOUNT_ID"),
provider: provider
)
client = OpenAI::Client.new(workload_identity: workload_identity)
response = client.responses.create(
model: "gpt-6.1-terra",
input: "Say hello from Oracle Cloud Infrastructure workload identity federation."
)
puts(response.output_text)
当 OpenAI SDK 需要续期工作负载身份凭据时,主体令牌提供方会请求新的 Oracle 令牌。切勿打印或持久化存储 Oracle 主体令牌或换取的 OpenAI 访问令牌。
- 如果只应允许一个工作负载访问,请使用
ipst_instance 映射单个实例。
- 仅当某个区间中所有符合条件的实例都应共用同一映射时,才使用
ipst_compartment。
- 添加
domain_id 或 ca_ocid,将访问范围限定在指定的身份域或租户内。
- 为每个应用在每个环境中分别使用独立的 OpenAI 服务账号。
- 在依赖 Pod 级隔离之前,请先确认 OKE 令牌是否代表工作节点。
- 使用 Oracle 签发的令牌中实际包含的受众值,不要假定令牌使用 OpenAI 专属受众。
- 如果您的身份域无法使用 OIDC 发现,请在 Oracle 轮换签名密钥时同步轮换已上传的公钥。