For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション
Theme

おすすめ

はじめに

基本概念

SDK と CLI

クラウドプロバイダー

リソース

レガシー API

API ダッシュボード
ChatGPT を試す

非対称鍵の設定

クラウドで管理する公開鍵を OpenAI に登録

クラウドプロバイダーで管理する RSA-3072 の非対称鍵ペアを OpenAI に登録します。

秘密鍵は AWS KMS、Azure Key Vault、Google Cloud KMS のいずれかに保管されます。OpenAI は登録時に、対応する公開鍵のコピーを保存します。

鍵を登録しても、製品機能やストレージは設定されません。このガイドでは、PSP の復号に使用する鍵を扱います。

事前準備

  • 組織 ID を用意します。クラウド側の信頼関係の設定、鍵の登録、API へのアクセスには、すべて同じ組織を使用してください。
  • 外部鍵の読み書き権限を持つ組織の管理用 API キーを作成し、OPENAI_ADMIN_KEY に安全な方法で読み込みます。プロジェクトの推論用 API キーは使用できません。
  • RSA-3072 鍵を有効な状態で作成し、このガイドで説明する範囲に限定して公開鍵の読み取り権限を OpenAI に付与できることを確認します。
  • 秘密鍵の使用は、権限のあるユーザーに限定します。古いバージョンの鍵を必要とするレコードがある間は、そのバージョンを保持してください。

クラウド側での鍵の設定

鍵を登録する前に、利用するプロバイダーの手順に従ってください。どのプロバイダーでも RSA-3072 を使用し、OpenAI には公開鍵とメタデータの読み取り権限のみを付与します。

鍵の登録

以下の例では curl と Bash 互換のシェルを使用します。OPENAI_ADMIN_KEY を安全な方法で読み込んでから、組織 ID を設定します。

API_BASE="https://api.openai.com/v1"
ORG_ID="<OPENAI_ORG_ID>"

: "${OPENAI_ADMIN_KEY:?Load your organization admin key securely}"

KEYS_URL="$API_BASE/organization/external_keys"

登録リクエストの準備

purpose に指定できる列挙値は ekm（デフォルト）と psp_decryption です。このガイドで扱う非対称鍵には psp_decryption を使用してください。ekm は Enterprise Key Management（EKM）用です。

利用するプロバイダーのリクエストを registration.json として保存します。JSON ではシェル変数が展開されないため、例の値を実際の値に置き換えてください。

AWS KMS のリクエスト

{
  "type": "aws",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-aws",
  "role_arn": "<CUSTOMER_ROLE_ARN>",
  "external_id": "<OPENAI_ORG_ID>",
  "kms_arn": "<CUSTOMER_KMS_KEY_ARN>"
}

Azure Key Vault のリクエスト

{
  "type": "azure",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-azure",
  "tenant_id": "<CUSTOMER_TENANT_ID>",
  "vault_uri": "https://<CUSTOMER_VAULT_NAME>.vault.azure.net",
  "key_name": "<OPENAI_ORG_ID>--asymmetric-key",
  "key_version": "<CUSTOMER_KEY_VERSION>"
}

Google Cloud KMS のリクエスト

{
  "type": "gcp",
  "purpose": "psp_decryption",
  "name": "asymmetric-key-gcp",
  "workload_identity_project_number": "<CUSTOMER_GCP_PROJECT_NUMBER>",
  "workload_identity_pool_id": "openai-keys",
  "workload_identity_provider_id": "openai-google",
  "audience": "<OPENAI_ORG_ID>",
  "kms_project_id": "<CUSTOMER_KMS_PROJECT_ID>",
  "kms_key_ring_name": "asymmetric-keys",
  "kms_key_name": "asymmetric-key",
  "kms_key_location": "us-central1",
  "kms_key_version": "1"
}

1. 鍵の登録と検証

curl --fail-with-body -sS "$KEYS_URL" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID" \
  -H "Content-Type: application/json" \
  --data @registration.json

登録時には、鍵を保存する前に検証が行われます。成功すると HTTP 200 が返り、レスポンスには extkey ID とプロバイダーの設定が含まれます。レスポンスフィールドの例を以下に示します。

{
  "id": "extkey_11111111111111111111111111111111",
  "object": "organization.external_key",
  "name": "asymmetric-key-gcp",
  "type": "gcp",
  "purpose": "psp_decryption",
  "api_project_ids": []
}

返された登録 ID を保存します。

KEY_ID="<EXTERNAL_KEY_ID>"

2. 鍵の再検証（任意）

GET は保存済みの登録情報を返します。POST /validate は現在のアクセス状況を再確認し、保存済みの公開鍵と照合して鍵の有効性を再検証します。レコードの復号やスナップショットの更新は行いません。

curl --fail-with-body -sS "$KEYS_URL/$KEY_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"
curl --fail-with-body -sS -X POST "$KEYS_URL/$KEY_ID/validate" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

成功時のレスポンス（HTTP 200）は次のとおりです。

{ "status": "success" }

鍵、権限、ネットワークの設定を変更した場合は、再度検証してください。IAM の設定を変更した場合は、変更が反映されてから再試行してください。

登録した鍵を PSP の復号に使用するには、プロジェクトでその鍵を選択します。

鍵の一覧の取得

purpose=psp_decryption を指定すると、この用途で登録した非対称鍵の一覧を取得できます。フィルターを省略するとすべての用途の登録情報が返り、purpose=ekm を指定すると EKM 用の登録情報のみが返ります。

curl --fail-with-body -sS --get "$KEYS_URL" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID" \
  --data-urlencode "purpose=psp_decryption" \
  --data-urlencode "order=asc" \
  --data-urlencode "limit=20"

has_more が true の間は、after に last_id の値を指定して次のページを取得します。purpose、order、limit は変更しないでください。

鍵の置き換え

  1. AWS では新しい鍵を、Azure または GCP では鍵の新しいバージョンを作成し、読み取り権限を付与します。
  2. 新しい鍵またはバージョンを登録します。
  3. プロジェクトで新しい extkey ID を選択し、選択内容を確認します。

登録情報は登録時点のスナップショットであり、クラウド側で鍵をローテーションしても更新されません。古い秘密鍵を必要とするレコードがある場合は、その秘密鍵を保持してください。選択する鍵を変更しても、既存のレコードは移行されません。

鍵の削除

登録を削除する前に、アクティブなすべてのプロジェクトで鍵の選択を解除するか、別の鍵を選択してください。

curl --fail-with-body -sS -X DELETE "$KEYS_URL/$KEY_ID" \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "OpenAI-Organization: $ORG_ID"

削除に成功すると HTTP 200 が返り、レスポンスには object: "organization.external_key.deleted" が含まれます。クラウド側の鍵は削除されません。

トラブルシューティング

エラー 確認事項
401 または 403 組織の管理用 API キーを使用し、外部鍵の登録に必要な権限があることを確認してください。
400 external_key_provider_error クラウド側の信頼関係、読み取り権限、ネットワークアクセス、鍵が有効かどうか、鍵のアルゴリズムを確認してください。
400 リクエスト検証エラー 用途、対象の AWS 鍵の ARN、Azure または GCP の鍵の正確なバージョンを確認してください。
404 登録 ID と組織を確認してください。削除済みの登録や別の組織の登録は使用できません。
external_key_used_by_active_projects アクティブなすべてのプロジェクトで鍵の選択を解除するか、別の鍵を選択してください。
鍵が登録時の鍵と一致しない 置き換え用の鍵を登録し、新しい ID を選択してください。

サポートに問い合わせる際は、エラーの内容と x-request-id をお知らせください。認証情報は決して共有しないでください。

関連ガイド