文書Q&AワークフローでOpenAI APIキーを安全に管理する
OpenAIを使った文書Q&Aアプリを安全に運用するための実践的な方法を解説します。認証情報の分離、最小権限の設定、ログの機密情報のマスキング、出典表示、キーの安全なローテーションを紹介します。
要約 · TL;DR
文書Q&Aアプリでは、OpenAIアプリケーション用の認証情報をブラウザー、サンドボックス、ソースファイル、ログに置かず、信頼できるサーバー側のシークレットストアで管理します。ワークロードごとに必要なアクセス権だけを付与し、ログから機密情報を除外したうえで、手順を定めて認証情報を切り替えます。回答には出典を添え、ユーザーが取得した文書に照らして内容を確認できるようにします。
要点
- OpenAIアプリケーションキーは、エージェント生成コードや、信頼できない実行環境の外で管理します。
- 専用のプロジェクトまたはワークロード境界を設け、アプリケーションに必要なAPI権限だけを付与します。
- 認証情報、文書本文、完全なプロンプトではなく、リクエストID、処理時間、出典IDを記録します。
- 回答には文書IDとページまたはセクションの参照を付けます。流暢な回答を正しさの証拠とみなしてはいけません。
- 新しい認証情報をデプロイして通信を確認した後、古いものを失効させます。漏えいが疑われる場合は直ちに失効させます。
目次 (6)
文書Q&Aシステムでは、適切な資料に基づいて回答することと、認証情報を資料処理の経路から切り離して守ることの両方が重要です。安全性を重視するなら、信頼できるアプリケーションサーバーからOpenAIを呼び出し、検索と出典の処理は明示的に自社のワークフロー内で行うのが基本です。アプリケーションキーをブラウザー、文書、プロンプト、ソースリポジトリ、エージェントがアクセスできるサンドボックスに置かないでください。
信頼境界を設ける
一般的な処理の流れは次のとおりです。ユーザーが質問し、アプリケーションが許可された文書ストアから関連箇所を取得します。サーバーは質問と選択した箇所をOpenAIに送り、アプリケーションはそれらの参照情報とともに回答を返します。キーはサーバー側のマネージドシークレットストアなど、保護された設定に保存します。ユーザーに送信するコードや、環境を調査できるワークロードには含めません。
OpenAIのサンドボックスセキュリティガイダンスは、エージェントが生成したコードから、その環境で利用可能なファイル、認証情報、ネットワークリソースにアクセスできる可能性があると警告しています。また、ワークロードの分離、データを共有すべきでない場合の環境分離、アプリケーションやワークロードごとのOpenAIプロジェクトの利用、アプリケーションAPIキーを環境外に保管することを推奨しています。さらに、キーをイメージ、ソースコード、ログに埋め込まないよう求めています。詳しくはOpenAIのサンドボックスセキュリティガイダンスを参照してください。
文書Q&Aでは、アップロードされた文書とモデル生成コードを信頼できない入力として扱う必要があります。検索ワーカーには、タスクに必要な文書とツールだけを渡します。推論のために質問を送る必要があるからといって、制限のないアプリケーション認証情報まで継承させてはいけません。
権限を制限し、認証情報を分ける
関係のないワークロード間で汎用キーを共有せず、このアプリケーション専用のプロジェクトまたは認証情報の境界を設けます。実装で実際に使用するAPI操作に対し、利用可能な最小限の権限を付与してください。引用したOpenAIのガイダンスでは、セッションに api.agents.read と api.agents.write、推論に api.responses.write、Vaultの管理に api.vaults.read と api.vaults.write を指定しています。これらは記載されたAgents APIのユースケースに関する例です。すべての権限を既定で付与せず、実際に呼び出すAPIに必要な権限を確認してください。
実行環境からOpenAIに接続する必要がある場合、ガイドではその接続用に別の環境キーを使う方法を説明しています。このキーは環境の接続を許可しますが、ほかのAPI操作を認可することはできないとされています。アプリケーションキーとは分けて管理してください。サードパーティーサービスの認証情報は、アプリケーションまたは信頼できるプロキシに保管します。生成コードから読み取れる環境に、長期間有効なシークレットを注入しないでください。
運用に必要な情報を保ちつつログをマスキングする
ログは検索結果が空になる原因、リクエストの失敗、出典の欠落などを調査するのに役立ちます。一方、完全なプロンプトや文書には、個人情報、機密情報、商業上の重要情報が含まれる可能性があります。たとえば、運用に必要な情報だけを記録します。
- リクエストID、タイムスタンプ、ステータス、応答時間。
- デバッグに役立つ場合は、モデル名とアプリケーションのバージョン。
- 取得した全文ではなく、内部文書IDとページまたはセクションの参照。
- リクエストヘッダーやシークレットの値ではなく、機密情報を除いたエラー分類。
既定では、認証ヘッダー、APIキー、ユーザーの完全なプロンプト、文書の全文を記録しないでください。一時的に内容を含むデバッグが必要な場合は、アクセスを制限した管理下の手順を設け、期間を限定し、削除日を明確にします。アプリケーション、プロキシ、トレース、エラー報告の各システムも確認してください。メインのアプリケーションロガーでマスキングしても、ほかの記録箇所が自動的にサニタイズされるわけではありません。
ログ記録の例を示します。
log_event(
request_id="generated-request-id",
outcome="success",
retrieved_sources=["policy-17:p4", "handbook-03:section-2"],
credential="[never include]",
prompt="[omit or redact]",
passage_text="[omit or redact]"
)
これは疑似コードであり、テスト済みのOpenAI SDKの例ではありません。利用するログシステムに合わせて変更し、イベントがアプリケーションプロセスの外に送られる前にシークレットが除去されることを確認してください。
出典表示を回答の仕様に含める
モデルに、回答後に出典を作り出すよう求めてはいけません。検索時に出典メタデータを保持し、各箇所を文書IDとページ、セクション、またはURLに結び付け、その情報を回答生成ステップに渡します。アプリケーションが想定する形式、つまり取得した文書だけを出典とする「回答+参照」を要求します。表示する前に、アプリケーションコードで参照先を検証してください。
関連する箇所が見つからない場合は、手元の文書では回答を裏付けられないと伝えるか、質問を絞るようユーザーに求めます。回答中の主張を取得した出典に結び付けられない場合は、裏付けがないことを示すか、その主張を省きます。参照先が実在し、その主張を裏付ける証拠が含まれていて初めて、引用は役に立ちます。具体的な検索や回答形式の実装は、選択するAPIによって異なります。ここで引用したセキュリティガイダンスは、文書Q&Aや出典表示の実装方法を定めるものではありません。
認証情報のローテーション手順を定める
インシデントが起きる前に手順を文書化しておきます。実用的な手順は次のとおりです。
- 現在の認証情報を使うアプリケーション、プロジェクト、シークレットストアのエントリ、サービスを特定します。
- 必要最小限のアクセス権を保った代替の認証情報を作成し、承認済みのシークレットストアに保管します。
- 管理された設定変更を通じて代替の認証情報をデプロイします。デプロイ中に値を表示したり、ビルド成果物に含めたりしないでください。
- 通常のワークフローでテスト質問を送信します。推論が成功すること、出典をたどれること、ログにシークレットや文書本文が含まれないことを確認します。
- エラーを監視し、代替の認証情報が使われていることを確認してから、古い認証情報を失効させます。デプロイシステムやローカル開発環境に残ったコピーも削除します。
- 漏えいが疑われる場合は、該当する認証情報を直ちに失効させ、アクセスとログを調査して、新しい認証情報を発行します。通常のローテーション時期を待ってはいけません。
OpenAIのガイダンスでは、必要に応じてキーをローテーションまたは失効させ、漏えいが疑われる場合は認証情報を直ちに失効させるよう述べています。組織では、リスク、ポリシー、運用上の制約に基づいて独自のローテーション間隔を定めてください。引用した情報源に、すべてに適用できる共通のスケジュールは示されていません。
リリース前のチェックリスト
- アプリケーションキーはサーバー側で管理され、ブラウザーやエージェント生成コードからアクセスできない。
- 必要に応じて専用のプロジェクトまたは環境を用意し、ワークロードを適切に分離している。
- 権限はアプリケーションに必要な操作だけに制限されている。
- ログにキー、認証ヘッダー、生のプロンプト、取得した文書の全文が含まれない。
- 回答には、取得した文書への検証済みの参照が含まれている。
- 代替の認証情報をデプロイし、古いものを失効させる担当者が決まっている。
設計上の要点はシンプルです。認証情報を文書処理環境の外に保管し、出典を取得した情報源までたどれるようにします。これにより、ワークロードが侵害された場合の影響を抑えながら、回答の根拠をユーザーが確認できるようになります。
よくある質問
ブラウザーベースの文書Q&AアプリにOpenAI APIキーを置いてもよいですか?
アプリケーションキーをブラウザーのコードに公開してはいけません。保護された設定またはシークレットマネージャーからキーを取得し、信頼できるサーバー側コンポーネントからOpenAIにリクエストを送ってください。
回答をデバッグするために、プロンプトや取得した文書の本文をログに記録すべきですか?
既定では避けてください。リクエストID、ステータス、処理時間、出典IDを記録する方法を優先します。一時的に内容を含むデバッグが必要な場合は、アクセスを制限し、削除期限を設定したうえで、認証情報が記録されないようにしてください。
OpenAI APIキーはどれくらいの頻度でローテーションすべきですか?
引用したOpenAIのセキュリティガイダンスは、必要に応じてキーをローテーションまたは失効させるよう述べていますが、一律の間隔は定めていません。組織のリスクとポリシーに応じてスケジュールを決め、漏えいが疑われる場合は直ちに失効させてください。
文書Q&Aの出典を信頼できるものにするにはどうすればよいですか?
検索時に文書IDとページ、セクション、またはURLのメタデータを保持し、参照先を検索結果に含まれる文書だけに限定したうえで、表示前に各参照を検証します。モデルに出典を作り出させてはいけません。
関連記事
Guides
文書質問応答におけるOpenAI API障害の診断
認証、レート制限、タイムアウト、出典付き回答の不備に対処するための実践的なトラブルシューティングガイドです。
Guides
Kimi K3.1 Pro Highspeedで文書Q&Aを行う場合のコスト試算
Kimi K3.1 Pro Highspeedを使った文書質問応答の再現可能なコスト試算です。公式価格とOneMux価格、キャッシュの前提、ワークロードの計算方法を紹介します。
Guides
カスタマーサポートのトリアージでOpenAI APIキーを安全に使う方法
カスタマーサポートのトリアージでOpenAIを使うための実践的なセキュリティ手順を解説します。APIキーの保護、ログのマスキング、権限の最小化、認証情報のローテーション、人による承認について紹介します。
Guides
ドキュメントQ&AにおけるGemini 4 Argon APIコスト:再現可能な試算
明示的なトークン数の前提、出典の明記、キャッシュ利用のケース、公開されているOneMux価格との比較をもとに、ドキュメントQ&AにおけるGemini 4 Argon APIのコストを試算します。