認証情報を漏らさずにOpenAI APIの障害を調査する方法
APIキーを保護し、権限を最小限に抑え、認証情報のローテーションを計画しながら、OpenAI APIの障害を有用なシグナルで調査する実践ガイドです。
要約 · TL;DR
OpenAI APIリクエストが失敗したときは、秘密情報や機微なコンテンツをログに残さず、原因特定に必要な証拠を保全します。認証情報は用途ごとに分け、利用できる場所を制限し、インシデント発生前にローテーション手順をリハーサルしておきましょう。
要点
- APIキー、Authorizationヘッダー、プロンプトやレスポンスの全文ではなく、リクエストの結果と安全な識別情報を記録しましょう。
- 役割ごとに認証情報を分け、ワークロードに必要な権限だけを付与しましょう。
- ステータス、エラーの分類、所要時間、リクエストIDは診断に役立つシグナルです。リクエスト内容を露出する理由にはなりません。
- 実用的なローテーション計画には、新しい認証情報の用意、デプロイ、検証、古い認証情報の失効が含まれます。
目次 (5)
ログに認証情報や不要な顧客データを含めず、運用上の証拠を残せば、OpenAI APIのインシデントをより簡単に調査できます。まず、成功以外のステータス、タイムアウト、アプリケーション例外などの障害シグナルを確認し、リクエストIDと影響を受けたデプロイに関連付けます。信頼できないコードやエージェント生成コードから読み取れる環境にAPIキーを置かないでください。
安全な診断記録を作成する
APIリクエストごとに記録するのは、次の4点を明らかにするために必要な情報だけにします。発生時刻、リクエストを送ったワークロード、発生した障害の種類、プロバイダー側の証拠とイベントを関連付けられるかどうかです。
有用な記録には、タイムスタンプ、独自の不透明な操作ID、エンドポイントのカテゴリ、HTTPステータス、経過時間、再試行回数、返却された場合はプロバイダーのリクエストIDなどが含まれます。例外オブジェクトをそのまま出力するのではなく、例外クラスや機微な情報を除いたエラーカテゴリを記録してください。一部のライブラリでは、例外メッセージにリクエストの詳細が含まれることがあります。レビュー済みの手順で具体的な必要性と適切な保護策が定められていない限り、プロンプト、レスポンス、Authorizationヘッダー、未加工のリクエスト本文やレスポンス本文を通常のログに含めないでください。
次のPythonコードは、テスト済みの統合例ではなく、参考パターンです。シークレットの取得関数とレスポンス処理は、アプリケーションやSDKによって異なります。この例では、リクエスト本文や認証情報を意図的にログへ出力しません。
import logging
import time
import uuid
logger = logging.getLogger(__name__)
def send_request(client, payload):
operation_id = str(uuid.uuid4())
started = time.monotonic()
try:
result = client.responses.create(**payload)
logger.info(
"openai_request_succeeded",
extra={
"operation_id": operation_id,
"elapsed_ms": round((time.monotonic() - started) * 1000),
"provider_request_id": getattr(result, "_request_id", None),
},
)
return result
except Exception as exc:
# Do not log str(exc), request headers, or payload here.
logger.error(
"openai_request_failed",
extra={
"operation_id": operation_id,
"elapsed_ms": round((time.monotonic() - started) * 1000),
"exception_type": type(exc).__name__,
},
)
raise
このパターンを採用する前に、クライアントからリクエストIDをどのように取得できるか、例外メッセージに機微な情報が含まれる可能性があるかを確認してください。トレース、エラー報告、プロキシログ、サポート用データにも同じマスキングルールを適用しましょう。アプリケーションログだけをサニタイズしても十分ではありません。
障害シグナルから原因を絞り込む
ステータスコードや例外は手がかりであり、それだけで原因を完全に特定できるわけではありません。デプロイ後に認証エラーが急増した場合は、認証情報が設定されていない、無効である、または誤った方法で渡されている可能性があります。レート制限の応答が増加した場合は、リクエスト量や同時実行数が変化した可能性があります。タイムアウトの原因としては、ネットワークアクセス、上流のレイテンシ、短すぎるクライアントタイムアウトなどが考えられます。プロバイダーから正常なレスポンスが返った後にユーザーリクエストが失敗するなら、アプリケーション側の解析処理や下流の問題かもしれません。
デプロイ前後の障害率とレイテンシを比較し、ワークロードや環境ごとに結果を分けて確認してください。シークレットの値でグループ化したり、2つのシステムが同じキーを使っているか「確認」するために値をログへ出力したりするのは避けましょう。サービスがどの認証情報を使用しているか確認する必要がある場合は、承認された手段でシークレットマネージャーの参照先とデプロイ設定を調べてください。
認証情報を分けて利用を制限する
OpenAIのサンドボックスセキュリティガイダンスでは、コンピューティング環境の分離、データを共有してはならないワークロード間での環境分割、アプリケーションまたはワークロード専用のOpenAIプロジェクトを推奨しています。また、アプリケーションAPIキーとエグゼキューター環境キーを区別しています。後者は環境間の接続を目的としたものであり、ほかのAPI操作を許可するものではありません。このガイダンスには、Agents APIのセッション、推論、Vault管理に関する個別の権限が記載されています。ワークロードに必要な権限だけを割り当ててください。詳しくはOpenAIのサンドボックスセキュリティガイダンスをご覧ください。
エージェント生成コードから読み取れる環境にアプリケーションキーを置かないでください。キーをソースコード、コンテナイメージ、ログに埋め込むのも避けましょう。サードパーティの認証情報について、このガイダンスでは、シークレットを環境の外部に保管し、適用可能な場合はプロキシやVaultベースの方法など、信頼できる仕組みを通じて渡すことを推奨しています。環境に注入したシークレットは、その環境で実行されるコードから引き続き利用できます。注入しただけでアクセスできなくなるわけではありません。
認証情報のローテーション手順を定める
インシデントが起きる前に、次の手順を書き出してリハーサルしておきましょう。
- 準備: 認証情報の所有者、権限、利用するサービス、シークレットマネージャー内の保管場所を特定します。認証情報を作成、デプロイ、失効できる担当者を確認します。
- 置き換え: 必要な権限だけを持つ新しい認証情報を作成します。チケット、チャット、ソースリポジトリではなく、承認済みのシークレットマネージャーに保管します。
- デプロイ: 通常のリリースプロセスに従って、対象のワークロードを更新します。新旧の認証情報を併用できる場合は、検証に必要な最短期間だけ古い認証情報を残します。
- 検証: リスクの低いリクエストを送り、成功状況、障害率、ログを確認します。古い認証情報に依存しているサービスが残っていないことも確認します。
- 失効とレビュー: 古い認証情報を失効させます。漏えいが疑われる場合は、定期ローテーションの日を待たず、失効を優先して、影響を受けたワークロードとログを調査します。
ローテーション直後にリクエストが失敗した場合は、サービスが新しいシークレットを実際に受け取ったか、再起動またはシークレットへのアクセス更新が行われたか、新しい認証情報に適切な権限があるかを確認してください。必要な操作を確認せず、権限エラーを解消するために広範なアクセス権を付与してはいけません。
インシデント対応の簡易チェックリスト
- 障害は特定のワークロード、環境、リリースだけで発生していますか?
- ステータス、レイテンシ、再試行回数、安全なリクエスト識別情報に傾向が見られますか?
- ログにAuthorizationヘッダー、キー、不要なプロンプトやレスポンスの内容が含まれていませんか?
- 認証情報は承認済みのシークレット管理経路を通じて保管・受け渡しされていますか?
- 関係のないサービスを変更せずに、認証情報を置き換えて失効できますか?
目的は何でもログに残すことではありません。認証情報、トラフィック、ネットワーク、アプリケーションの各障害を見分けるために十分な安全な証拠を残し、認証情報の漏えいが疑われた場合にすばやくローテーションできるようにすることです。
よくある質問
OpenAI APIリクエストの失敗時には、何をログに記録すべきですか?
タイムスタンプ、独自の不透明な操作ID、エンドポイントのカテゴリ、HTTPステータスまたは機微な情報を除いたエラーカテゴリ、経過時間、再試行回数、取得可能な場合はプロバイダーのリクエストIDを記録します。APIキー、Authorizationヘッダー、リクエストやレスポンスの全文は、原則としてログに残さないでください。
エージェント生成コードからAPIキーを利用できるようにしてもよいですか?
必要のないコードにアプリケーションAPIキーを公開しないでください。OpenAIのサンドボックスセキュリティガイダンスでは、アプリケーションキーを環境の外部に保管するよう案内しており、エージェント生成コードがその環境で利用可能なファイルや認証情報にアクセスできると説明しています。
OpenAI APIキーはいつローテーションまたは失効させるべきですか?
定められた運用スケジュールに従って認証情報をローテーションし、漏えいが疑われる場合は直ちに失効させてください。完全な手順には、新しい認証情報への置き換え、デプロイ、検証、古い認証情報の失効が含まれます。
認証情報をローテーションした後にリクエストが失敗するのはなぜですか?
ワークロードがキャッシュ済みまたは古いシークレットを使い続けている、設定が更新されていない、新しい認証情報に必要な権限がない、といった可能性があります。認証情報そのものをログに出さずに、デプロイされたシークレットの参照先と必要な権限を確認してください。
関連記事
Guides
カスタマーサポートのトリアージでOpenAI APIキーを安全に使う方法
カスタマーサポートのトリアージでOpenAIを使うための実践的なセキュリティ手順を解説します。APIキーの保護、ログのマスキング、権限の最小化、認証情報のローテーション、人による承認について紹介します。
Guides
文書Q&AワークフローでOpenAI APIキーを安全に管理する
OpenAIを使った文書Q&Aアプリを安全に運用するための実践的な方法を解説します。認証情報の分離、最小権限の設定、ログの機密情報のマスキング、出典表示、キーの安全なローテーションを紹介します。
Guides
OpenAI APIの認証・レート制限・タイムアウト・不正レスポンスを安全に診断する方法
認証、リクエスト制限、タイムアウト、不正なレスポンスなどのOpenAI APIエラーを、認証情報やユーザーデータを漏らさず診断するための実践的なガイドです。
Guides
APIインシデント診断に向けたClineの設定
APIインシデントを診断するCline SDKセッションを設定し、プロバイダーに依存しないランタイム設定を選択。観測可能な障害の兆候から問題を切り分けます。