你可以使用 Oracle Cloud Infrastructure (OCI) 作為工作負載身分提供者,以 Oracle Identity Cloud Service (IDCS) 存取權杖換取短效 OpenAI 存取權杖。OCI 執行個體主體會簽署權杖交換要求,並將要求傳送至同一租用戶中的身分網域。OpenAI 會驗證換得的權杖,並授權 OCI 工作負載以對應的 OpenAI 服務帳戶身分執行操作。
這項設定不需要 OpenAI API 金鑰或自訂 Oracle OAuth 資源應用程式,也不需要授予動態群組存取自訂應用程式的權限。
在具備執行個體主體的 OCI Compute 執行個體上執行工作負載。如果使用 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 取得的公開 JWKS。
-
只有在需要衍生屬性時,才新增屬性轉換。 你可以在服務帳戶對應的判斷條件中直接使用 Oracle 的原始宣告,例如 ipst_instance、ipst_compartment、domain_id 和 ca_ocid。若要明確定義衍生的執行個體屬性,請輸入屬性名稱 instance 和運算式 assertion.ipst_instance,以建立 openai.instance。
Oracle 的 OpenID Connect 探索參考文件說明了自訂探索的重要性。探索文件可以將全域 URL https://identity.oraclecloud.com/ 宣告為簽發者,同時在租用戶專屬的身分網域上發布權杖端點和 jwks_uri。請在 OIDC 簽發者 URL 中保留全域簽發者 URL,並在自訂 OIDC 探索 URL 中填入租用戶的網域 URL。
如果身分網域在權杖簽發者的 URL 發布探索中繼資料,請讓自訂探索維持停用,並使用標準 OIDC 探索。如果 OpenAI 無法存取租用戶的探索文件或簽章金鑰端點,請停用自訂探索、啟用使用已上傳的 JWKS 驗證權杖,並上傳從 https://<identity-domain>/admin/v1/SigningCert/jwk 取得的租用戶公開 JWKS。自訂探索與已上傳的 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。
下列範例使用 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-5.6-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-5.6-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 輪替簽章金鑰時,一併輪替已上傳的公開金鑰。