X.509 証明書を使ったワークロード ID フェデレーションの設定

X.509 ワークロード ID フェデレーションでは、ワークロードは TLS クライアント証明書が示す ID を、有効期間の短い OpenAI アクセストークンと交換できます。その後、ワークロードはアクセストークンと、API が受け入れるクライアント証明書の両方を使って OpenAI API を呼び出します。このフローではアクセストークンが API キーの代わりになります。クライアント証明書は引き続き必要です。

トークン交換のリクエストとレスポンスの詳細は、ワークロード ID のトークン交換リファレンスを参照してください。相互 TLS の権限、証明書の要件と有効化、mTLS ホスト、証明書のローテーションについては、相互 TLS ガイドを参照してください。

仕組み

X.509 を使ったワークロード ID の交換は、次の 5 つの段階で行われます。

1. 組織の既存の相互 TLS 設定で、信頼するルート証明書をアップロードして有効化します。
2. X.509 ワークロード ID プロバイダーは、検証済みのクライアント証明書から openai.* 属性を導出します。openai.subject には、空でない値を 1 つ導出する必要があります。
3. サービスアカウントのマッピングにより、導出した ID に、プロジェクト内の 1 つの OpenAI サービスアカウントを使用する権限が付与されます。
4. ワークロードは mtls.auth.openai.com の X.509 トークンエンドポイントに証明書を提示し、有効期間の短い Bearer トークンを要求します。証明書は TLS 接続時に提示するため、リクエスト本文に subject_token は含めません。
5. ワークロードは API の認可を受けるため、mtls.api.openai.com の API ルートに Bearer トークンとクライアント証明書を提示します。

API リクエストの認可時には、Bearer トークンと証明書が個別に評価されます。証明書だけでは OpenAI API の呼び出しは許可されません。

前提条件

次のものが必要です。

• 組織の相互 TLS 証明書とワークロード ID プロバイダーを管理する権限
• ワークロード用のプロジェクトとサービスアカウント
• クライアント証明書、その秘密鍵、および信頼するルート証明書までのチェーンを構成するために必要な中間証明書
• 組織またはプロジェクトで有効化された、信頼するルート証明書

秘密鍵はバージョン管理の対象外に置き、アクセスできるのはその鍵を使用するワークロードだけにしてください。秘密鍵、証明書の内容、返されたアクセストークンをログに記録しないでください。

相互 TLS で信頼する証明書の設定

X.509 ワークロード ID プロバイダーは、組織の既存の相互 TLS 証明書設定を使用します。プロバイダー自体が証明書をアップロードしたり、独自のトラストストアを管理したりすることはありません。

相互 TLS ガイドで、証明書の要件、mTLS ホスト、証明書を有効化したときの動作、CEL フィルター、クライアントの設定を確認してください。次に、組織設定 > セキュリティ > 相互 TLS を開き、信頼する証明書を PEM 形式でアップロードします。証明書は組織全体で有効化するか、X.509 ワークロード ID フェデレーションを使用するプロジェクトごとに有効化してください。

クライアント証明書が中間証明書を介してルート証明書につながる場合は、継続して使用するトラストアンカーを設定します。TLS ハンドシェイクでは、リーフ証明書、現在の中間証明書の順に提示してください。OpenAI はリクエストで提示された中間証明書を使用します。不足している中間証明書を証明書内の URL から取得することはありません。

X.509 プロバイダーの設定

X.509 プロバイダーを設定する手順は次のとおりです。

1. 組織設定 > セキュリティ > ワークロード ID プロバイダーを開き、ID プロバイダーを作成を選択します。
2. X.509 をプロバイダーの種類として選択し、名前を入力します。説明は任意です。X.509 プロバイダーでは、OIDC の発行者、オーディエンス、ディスカバリー、JWKS の設定は使用しません。作成後にプロバイダーの種類は変更できません。
3. 必要に応じて、詳細設定の属性条件に CEL 式を追加します。この条件を使うと、該当するマッピングを特定する前に証明書を拒否できます。
4. 属性変換で、必須の openai.subject 変換に空でない式を入力します。X.509 を選択すると、ダッシュボードに subject 行が追加され、openai. プレフィックスが表示されて属性名に適用されます。ワークロードの識別には、証明書の情報のうち、値が安定しているものを選んでください。
5. 必要に応じて、一意の openai.* 名を持つ変換を追加し、作成を選択します。

たとえば、次の設定では証明書のコモンネームを正規のサブジェクトとして使用し、組織単位をマッピング用の追加属性として利用できるようにします。

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

証明書の情報は assertion.subject と assertion.subject_alt_names で参照できます。マッピングに使用する変換結果はスカラー値である必要があります。追加する変換には、それぞれ一意の openai.* 名が必要です。

たとえば、属性条件に次の式を指定すると、プロバイダーが受け入れる証明書を本番環境用に限定できます。

assertion.subject.organizational_unit == "Production"

サービスアカウントのマッピングの作成

1. X.509 プロバイダーの詳細ページで、マッピングを作成を選択します。
2. 対象のプロジェクトとサービスアカウントを選択し、ワークロードに必要な API 権限だけを付与します。
3. キーと値のフィールドで、openai.subject の値が完全に一致することを条件にします。X.509 マッピングでは、アサーションを指定しない場合は空のオブジェクト（{}）を使用します。アサーションを指定する場合は、各キーが openai. で始まる必要があります。
4. 作成を選択します。

設定例を示します。

X.509 マッピングは、証明書から導出した openai.* 属性を照合します。sub、iss、aud などの JWT クレームを直接照合することはありません。

プロバイダー一覧にはプロバイダー ID が表示されます。マッピングの詳細には、選択したサービスアカウントとその ID が表示されます。ワークロードがトークン交換時に送信するので、両方の ID を控えておいてください。

SDK での X.509 ワークロード ID の使用

証明書チェーン、秘密鍵、プロバイダー、サービスアカウントの環境変数を設定します。

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"

証明書チェーンのファイルには、先頭にリーフ証明書を置き、その後に必要な中間証明書を並べてください。リクエスト本文に証明書データや subject_token を含めないでください。

これらの値を使って OpenAI SDK クライアントを設定します。SDK はトークン交換時と API リクエスト時にクライアント証明書を提示し、API リクエストを mTLS エンドポイントに送信します。有効期間の短いアクセストークンの更新も自動で行います。

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

これらの例を実行するには、ここで示す X.509 設定に対応したバージョンの OpenAI SDK が必要です。JavaScript では SDK 7.8.0 以降を使用し、ピア依存パッケージの undici もインストールしてください。他の言語で必要な SDK のバージョンは、Python が 3.6.0 以降、Go が 3.54.0 以降、Java が 4.55.0 以降、Ruby が 0.83.0 以降です。

Java の例では、PKCS12 キーストアを読み込んで X509ExtendedKeyManager を構築し、プラットフォームのデフォルトのトラストストアを使って X509TrustManager を構築します。この例では OPENAI_X509_KEYSTORE_PATH、OPENAI_X509_KEYSTORE_PASSWORD、OPENAI_X509_CERTIFICATE_ALIAS を設定してください。代わりに、PEM またはハードウェアを使用するマネージャーを SDK に渡すこともできます。

証明書の手動交換

トークン交換プロトコルの動作を直接確認したり、自分で実装したりするには、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

交換に成功すると、有効期間の短い通常の Bearer トークンが返されます。

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

scope プロパティは、一致するサービスアカウントのマッピングに権限が設定されている場合にのみ返されます。

有効期限に関する値は一例です。検証済みのクライアント証明書が先に期限切れになる場合、返されるトークンの有効期間は短くなることがあります。トークン交換のレスポンスフィールドで、expires_in と expires_at の単位と意味を確認してください。

成功時のレスポンスから access_token の値を読み取り、アプリケーションの認証情報ストアまたは OPENAI_WIF_ACCESS_TOKEN などの環境変数に保存します。この値は秘密情報として扱い、画面への出力、ログへの記録、コミットはしないでください。

OpenAI API の手動呼び出し

OPENAI_MODEL には、現在のデフォルトモデルである gpt-6-astra または対象プロジェクトで利用できる別のモデルを設定します。次に、Bearer トークンと、API が受け入れるクライアント証明書を API の mTLS エンドポイントに送信します。

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"

API キーの代わりに Bearer トークンを使用し、API リクエストでは引き続き、API が受け入れるクライアント証明書を提示してください。

Bearer トークンと証明書の間に暗号学的な結び付きはありません。最も簡単な設定は、トークン交換に使った証明書を API リクエストにも使うことです。ただし、現在適用されている同じ API mTLS ポリシーを単独で満たす別の証明書も使用できます。

トークンの有効期間と更新

X.509 ワークロード ID トークンの有効期間は最長 1 時間で、検証済みのクライアント証明書の有効期限を超えることはありません。トークン交換ではリフレッシュトークンは返されません。新しいアクセストークンを取得するには、証明書をもう一度交換してください。

手動で交換する場合は、expires_at をアクセストークンと一緒に保存し、その時刻より前に次の交換が実行されるようにスケジュールしてください。時計のずれやリクエストの遅延を見込んで、時間に余裕を持たせてください。例はトークン更新のガイドを参照してください。

中間証明書をローテーションしても、設定済みのルート証明書を変更する必要はありません。以降のトークン交換と API リクエストでは、新しい完全な証明書チェーンを提示してください。

トークン交換のトラブルシューティング

X.509 トークン交換では、汎用の OAuth エラーが返されます。証明書、ルート証明書、プロバイダー、マッピングの詳細は開示されません。

X.509 トークン交換が OIDC や通常の OAuth フローにフォールバックすることはありません。

制限事項

• X.509 ワークロード ID プロバイダーは、独自の証明書トラストストアを管理しません。
• Bearer トークンは証明書に紐付けられておらず、DPoP や cnf クレームも使用しません。
• 証明書を交換しても、証明書だけで API の認可を受けることはできません。API リクエストには引き続き、Bearer トークンと、API が受け入れるクライアント証明書が必要です。
• OpenAI は不足している中間証明書を AIA URL から取得しません。TLS ネゴシエーション時に完全な証明書チェーンを提示してください。
• このフローでは、OpenAI は証明書失効リスト（CRL）や OCSP による確認を行いません。証明書に関するインシデントへの対応は、相互 TLS のルート証明書、プロバイダー、マッピングの各設定で実施できる対策と、発行されるトークンの有効期間が短いことを踏まえて計画してください。
• このフローでは SPIFFE X.509-SVID には対応していません。SPIFFE ガイドで説明する方式では、引き続き JWT-SVID を使用します。