相互 TLS

相互 TLS（mTLS）は、OpenAI API へのリクエストに TLS クライアント証明書の検証を追加します。組織またはプロジェクトで信頼する証明書を有効にすると、その範囲のリクエストでは、通常の Bearer 認証情報に加えて、信頼設定を満たすクライアント証明書の提示が必要になります。

ワークロードがクライアントの秘密鍵を安全に保管でき、OpenAI が API リクエストを認可する前に証明書でクライアントの身元を確認する必要がある場合に、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 は、不足している中間証明書を認証局情報アクセス（AIA）の URL から取得しません。また、証明書失効リスト（CRL）やオンライン証明書状態プロトコル（OCSP）による確認も行いません。必要な証明書チェーンをすべて提示してください。インシデントには、証明書のローテーションや無効化など、利用者側の証明書ライフサイクル管理の仕組みで対応してください。

証明書の検証順序

OpenAI は、まずプロジェクトで有効な証明書を確認し、次に組織で有効な証明書を確認します。どちらにも有効な証明書がなければ、そのリクエストに mTLS による証明書検証は追加されません。

有効な証明書がある場合、OpenAI は次の順序でクライアントの身元を検証します。

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

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

チェーン検証に進むのは、直接検証が通常の不一致で終わった場合です。直接検証で発生したすべてのエラーが対象になるわけではありません。証明書データが不足しているか形式が不正な場合、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 ホストに通常の Bearer 認証情報とクライアント証明書を送信するには、次のようにします。

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 を使用します。交換で得られるのは有効期間の短い Bearer トークンです。証明書だけで API 認証ができるわけではありません。リクエスト形式の詳細は、ワークロード ID のトークン交換リファレンスを参照してください。

証明書のローテーション

既存のワークロードを稼働させたままトラストアンカーを切り替えるには、新旧のアンカーが同時に有効な期間を設けます。

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

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

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

設定エラーと一時的なサービスエラーは、次の固定のエラーコードで区別できます。

管理リクエストでは、mtls_certificate_invalid はアップロードした PEM データが検証に通らなかったことを示します。expired_certificate は証明書の残りの有効期間が短すぎるか、すでに期限が切れていることを示します。mtls_cel_policy_invalid はフィルターが検証に通らなかったことを示します。certificate_in_use が返された場合は、証明書を無効にしてから削除してください。

現時点の制限事項

• 1 つの組織がアップロードできる証明書オブジェクトは最大 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 クレーム、証明書にバインドされた Bearer トークンはいずれも使用しません。X.509 証明書を使用したワークロード ID フェデレーションの設定を参照してください。