相互 TLS

相互 TLS（mTLS）は、OpenAI API リクエストに TLS クライアント証明書の検証を追加します。組織またはプロジェクトで信頼する証明書を有効化すると、そのスコープのリクエストでは、通常の Bearer 認証情報に加えて、受け入れ可能なクライアント証明書を提示する必要があります。

ワークロードがクライアントの秘密鍵を安全に保持でき、API リクエストを認可する前に OpenAI に証明書の ID を検証させたい場合は、mTLS を使用します。mTLS は、API キー、サービスアカウントの認証情報、ワークロード ID のアクセストークンを置き換えるものではありません。

mTLS 設定前の準備

どの API 組織でも、通常のロールベースのアクセス制御（RBAC）を通じて mTLS を管理できます。

• api.mtls.read 権限を持つプリンシパルは、証明書設定の一覧取得、表示、テストを実行できます。
• api.mtls.write 権限を持つプリンシパルは、証明書のアップロード、更新、有効化、無効化、 削除を実行できます。

組織のオーナーロールにはこれらの権限が含まれていますが、 カスタムロールを通じて付与することもできます。詳しくは、OpenAI プラットフォームでの 権限管理を参照してください。

次のものを準備してください。

• 各ワークロード用のクライアント証明書とその秘密鍵
• クライアント証明書からトラストアンカーまでのパスを構築するために必要な中間証明書
• 組織またはプロジェクトレベルで有効化できる、安定して使用できる PEM 形式のトラストアンカー
• 本番環境のトラフィックで mTLS を有効にする前に使用する、重要度の低いプロジェクトとテスト済みの復旧手順

秘密鍵はソース管理の対象外にしてください。秘密鍵、証明書の内容、Bearer 認証情報をログに記録しないでください。

トラストアンカーのアップロードと有効化

アップロードすると証明書は保存されますが、mTLS は強制されません。リクエストの動作が変わるのは、有効化した時点です。

1. 組織の設定 > セキュリティ > 相互 TLSを開きます。
2. 証明書オブジェクトごとに、PEM 形式のトラストアンカーを 1 つアップロードします。認証局とローテーションの世代を識別できる名前を付けてください。
3. 必要に応じて、CEL フィルターを追加し、 そのアンカーが受け入れる検証済みクライアント証明書を制限します。
4. まず、重要度の低いプロジェクトで証明書を有効化します。 利用を予定しているすべてのワークロードから、mTLS API ホスト経由で 代表的なリクエストを送信します。
5. 検証に成功したら、他のプロジェクトまたは組織で証明書を有効化します。

API を通じて証明書を管理することもできます。

必要な api.mtls.read または api.mtls.write 権限を持つ認証情報を使用してください。 リクエストとレスポンスのスキーマについては、組織の証明書の API リファレンスを参照してください。

証明書の要件

証明書オブジェクトごとに、PEM 形式のトラストアンカーを 1 つ使用します。アップロードするデータには、アップロード時点から有効期限まで 1 日を超える期間が残っている有効な証明書を含める必要があります。クライアント証明書には、リクエストの検証用に認証局鍵識別子（AKI）を含める必要があります。

リクエストが mTLS の検証に合格するには、次の条件を満たす必要があります。

• クライアント証明書は、リクエスト時点で有効であり、TLS クライアント認証に適している必要があります。
• クライアント証明書から、組織またはプロジェクトレベルで有効化されているトラストアンカーまで、有効なパスを構築できる必要があります。
• パスに中間証明書が含まれる場合、クライアントは TLS ハンドシェイク中にそれらを提示する必要があります。
• 設定されたトラストアンカーとクライアントの証明書チェーンは、標準の X.509 クライアント証明書パス検証に合格する必要があります。

アップロードするデータに複数の PEM 形式の証明書が含まれる場合、リクエストの証明書チェーン検証では、設定された最初の証明書だけがアンカーとして使用されます。PEM バンドルとして扱われることを前提にしないでください。

OpenAI は、Authority Information Access（AIA）の URL から不足している中間証明書を取得せず、証明書失効リスト（CRL）や Online Certificate Status Protocol（OCSP）による確認も行いません。必要な証明書チェーンをすべて提示してください。インシデントには、証明書のローテーション、無効化、および独自の証明書ライフサイクル管理を通じて対応してください。

検証の順序

OpenAI は、組織レベルで有効化されている証明書より先に、プロジェクトレベルで有効化されている証明書を確認します。どちらのスコープにも有効化されている証明書がない場合、mTLS による証明書の確認はリクエストに追加されません。

有効化されている証明書がある場合、OpenAI は次の順序でクライアントの ID を検証します。

1. OpenAI はまず、既存の直接検証パスを試します。このパスでは、リクエストで提示された中間証明書を使用せず、有効化されているアンカーに対してクライアント証明書を直接検証します。
2. 直接検証パスで通常の不一致となった場合、OpenAI は、TLS 接続で提示されたクライアント証明書と中間証明書を使用して、リクエストの証明書チェーン検証を試みます。
3. パスの検証に成功し、有効化されている証明書に CEL フィルターが設定されている場合、OpenAI は検証済みのクライアント証明書に対してそのフィルターを評価します。

リクエストの証明書チェーン検証は、デフォルトで利用できます。

リクエストの証明書チェーンを使うパスは、通常の不一致が発生した場合のフォールバックであり、直接検証パスで発生するすべてのエラーから復旧するためのものではありません。証明書データの欠落や形式の不正、AKI の欠落、または直接検証パスでアンカーを選択した後に発生する確定的なエラーによって、提示されたチェーンでの検証を試みずにリクエストが失敗する場合があります。

CEL によるクライアント証明書のフィルタリング

アップロードした証明書には、任意で Common Expression Language（CEL）フィルターを付けて、そのアンカーが受け入れる検証済みクライアント証明書を制限できます。式の評価結果はブール値である必要があります。この式は、直接検証パスでもリクエストの証明書チェーンを使うパスでも、検証済みのクライアント証明書に対して実行されます。

CEL では、次のフィールドを参照できます。

• subject.common_name、subject.country_code、subject.organization、 subject.organizational_unit、subject.locality、subject.province、 subject.street_address、subject.postal_code
• subject_alt_names は、各エントリで type、value、oid を参照できるリストです。 サポートされる SAN のタイプ識別子は、DNS、EMAIL、IP_ADDRESS、URI、 CUSTOM です。

たとえば、本番環境用の組織単位と、特定の名前空間に属する DNS SAN を必須にするには、次のようにします。

subject.organizational_unit == "Production" &&
subject_alt_names.exists(san, san.type == DNS && san.value.endsWith(".example.com"))

証明書の検証に成功してもフィルターに一致しない場合は、 certificate_attribute_verification_failed で失敗します。OpenAI は、保存時の検証に合格しないポリシーを拒否します。

mTLS ホストの使用

API トラフィックは、api.openai.com の代わりに mTLS ホストに送信します。

mTLS はホスト単位で機能します。対応する API で呼び出すのと同じ /v1 ルートを使用し、 ワークロードが使用する各 API とモデルをテストしてください。 利用可能なルートやモデルは、リージョンのホストによって異なる場合があります。

たとえば、通常のベアラー認証情報とクライアント証明書をデフォルトの mTLS ホストに送信します。

1234567export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"

curl https://mtls.api.openai.com/v1/models \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer $OPENAI_API_KEY"

証明書チェーンファイルには、最初にクライアント証明書を配置し、その後に必要な中間証明書を配置してください。証明書のデータを HTTP ヘッダーやリクエスト本文で送信しないでください。

X.509 ワークロード ID フェデレーションでは、専用の交換エンドポイントを使用します。 正確なエンドポイントは POST https://mtls.auth.openai.com/oauth/token です。この交換では、 有効期間の短いベアラートークンが発行されます。証明書のみでの API 認証は提供されません。 リクエストの完全な形式については、ワークロード ID トークン交換の リファレンスを参照してください。

証明書のローテーション

既存のワークロードが動作し続けられるよう、新旧のトラストアンカーを併用する期間を設けてローテーションします。

1. 古いトラストアンカーを無効化せずに、新しいトラストアンカーをアップロードします。
2. 対象の各プロジェクトまたは組織レベルで、新しいトラストアンカーを有効化します。
3. 新しいトラストアンカーにつながるクライアント証明書を提示するようにワークロードを更新し、使用する各 mTLS ホストと API をテストします。
4. すべてのワークロードの移行が完了したら、古いトラストアンカーを無効化します。
5. 古い証明書は、組織とすべてのプロジェクトで無効化してから削除してください。

設定済みのトラストアンカーを変更せずに、中間証明書をローテーションできます。以降のリクエストでは、新しい完全な証明書チェーンを提示してください。

リクエストのトラブルシューティング

安定したエラーコードを使って、構成エラーと一時的なサービスエラーを区別します。

管理リクエストでは、mtls_certificate_invalid はアップロードされた PEM が検証に失敗したことを示します。 expired_certificate は有効期限までの期間が短すぎるか、すでに期限切れであることを示します。 mtls_cel_policy_invalid はフィルターが検証に失敗したことを示します。 certificate_in_use は証明書を削除する前に 無効化する必要があることを示します。

現在の制限事項

• 組織ごとに最大 50 個の証明書オブジェクトをアップロードできます。
• mTLS は通常の API 認証に証明書の検証を追加するものであり、証明書のみでの API 認可は提供しません。
• OpenAI は AIA から中間証明書を取得せず、CRL または OCSP による確認も行いません。
• Private Link は mTLS と互換性がありません。代わりに Azure のプライベートネットワーク経路が必要な場合は、 Private Linkを参照してください。
• サポートされている API mTLS ホストは mtls.api.openai.com、 mtls-us.api.openai.com、mtls-eu.api.openai.com です。 ほかのすべてのリージョンの API ホストに、対応する mTLS ホストがあるとは限りません。
• X.509 ワークロード ID フェデレーションはリフレッシュトークンを返しません。 また、DPoP、cnf クレーム、証明書にバインドされたベアラートークンも使用しません。 X.509 証明書を使用した ワークロード ID フェデレーションの構成を参照してください。