Analytics API トークンは識別子ではなく認証情報
API トークンはデータへのアクセスを許可します。秘密情報としてライフサイクルを設計し、一度だけ表示し、検証値を保存し、権限を絞り、いつでも失効できるようにします。
API トークンはユーザーやサイトを示すラベルではなく、認証情報です。有効なトークンを取得した人は、所有者として操作できる可能性があります。識別子のように扱うと、ログ、URL、サポート用のスクリーンショット、誰も失効方法を把握していない長期設定に入り込みます。
IETF が 2025年1月に公開した OAuth 2.0 セキュリティのベストプラクティスは、OAuth の脅威モデルとセキュリティ指針を更新しました。個人用 API トークンが OAuth アクセストークンとは限りませんが、基本原則は同じです。所持しているだけで使える認証情報は、転送中に保護し、目的のサービスに限定し、呼び出し元に必要な権限だけを与えます。
秘密情報は一度だけ表示する
実用的な推測を防げる十分なエントロピーを持つ、暗号学的に安全な乱数源でトークンを生成します。完全なトークンは作成時だけ返し、その後は識別用の非秘密プレフィックスと、照合用の一方向検証値を保存します。データベースがコピーされても、再利用できる平文認証情報より検証値の方が安全です。一般的なハッシュとパスワードハッシュを混同してはいけません。API トークンには高いランダム性が必要ですが、人間のパスワードには意図的に遅いハッシュ関数が必要です。
UI と API の応答で、トークンは一度だけ表示されると明示します。作成画面を離れた後は、元の秘密を再表示するのではなく、失効して再発行できるようにします。トークンをクエリパラメーター、ページ URL、Analytics イベント、エラーレポート、スクリーンショットに含めないでください。URL は認可ヘッダーよりも、ブラウザー履歴、Referer、プロキシログ、サポートチケットに残りやすいものです。
認証情報を適切な場所で送る
HTTP API では、TLS を介して Authorization ヘッダーでトークンを受け取ります。RFC 6750 は bearer token を「所持する人なら誰でも使える」ものと定義し、保存中や転送中の開示が悪用につながると警告しています。また URL がログに残りやすいため、URI のクエリパラメーターに bearer 認証情報を含めないよう勧めています。プロトコルが別の送信方法を要求し、脅威モデルが文書化されている場合を除き、クエリ文字列やリクエストボディ内のトークンは拒否します。
サーバーは要求された操作を処理する前にトークンを検証します。所有者と権限は信頼できるストレージから解決し、リクエスト内のユーザーやサイト所有者を権限の根拠にしません。アプリケーションログ、トレース、例外メッセージから秘密情報を除外します。運用上の相関が必要な場合は、トークンの非秘密 ID やプレフィックスを記録し、認証情報そのものは記録しません。
権限を絞り、有効期限と失効を設ける
トークンが許可するのは、目的に必要な最小限の権限です。製品が対応しているなら、ユーザーが特定のサイトや読み取り専用、または特定操作に限定できるようにします。1つのレポートを取得する自動化スクリプトに、アカウント全体の書き込み権限を暗黙に与えてはいけません。OAuth のセキュリティベストプラクティスはトークンの権限と audience の制限を扱っており、API が独自の不透明な形式を使う場合にも設計の参考になります。
有効期限と失効を基本機能として提供します。短い有効期間は漏えいした認証情報が使われ続ける時間を減らし、失効はインシデントや担当者・連携先の変更に対応します。ローテーションに重複期間が必要なら、その長さを制限し、どのトークンが有効かを表示します。失効は API 境界で適用し、ダッシュボードから隠すだけにしてはいけません。
Monoid のプログラマブル API では、ユーザーが作成する mnd_live_… トークンは不透明で、平文では一度だけ返し、SHA-256 ハッシュとして保存します。有効期限は任意で、論理的な失効にも対応します。この設計はデータベースを読まれても元の値を保護しますが、漏えいした有効なトークンを無害化するものではありません。ソース管理、CI 出力、ブラウザーバンドル、共有ターミナル履歴に含めず、漏えいの疑いがあれば新しいトークンを発行して旧トークンを失効させます。
ライフサイクルをテスト可能にする
作成、予定された権限での使用、無効または期限切れトークンの拒否、失効、同じトークンが使えなくなったことの確認まで、一連の流れをテストします。アカウントやサイトをまたいでアクセスできないこと、すべての endpoint が同じ認証・認可ルールを適用することも検証します。ログで認証情報がマスクされ、API 応答が保存済みトークンを返さないことを運用チェックに含めます。
秘密情報管理のライフサイクルには、作成、アクセス制御、ローテーション、監査、失効が含まれます。安全に保管するだけでは不十分です。所有者を特定し、権限を限定し、秘密を記録せずに漏えいを検知し、速やかに無効化できて初めて API トークンを保護できます。
Comments
Loading comments…