マップ API の認証

安全なマップ API 認証では、実行環境ごとに認証情報を分離します。ブラウザには公開を前提とし、承認済みオリジンと機能に厳しく制限した認証情報が必要です。バックエンドにはクライアントコードに決して入らず、サーバー間処理を認可する秘密鍵が必要です。両者を交換可能にしてはいけません。スコープを限定し、環境を分離し、利用を監視し、キーをローテーションし、認証失敗と認可失敗を区別します。Kaleidr は公開可能キー（kld_pk_live_…）とサーバーキー（kld_sk_live_…）で実装しています。

以下ではブラウザ／サーバー認証情報、オリジン、CORS、スコープ、ライフサイクル、マルチテナント境界、よくある誤りを扱います。詳細は開発者向け文書をご覧ください。SDK 構成はAI マップ SDK とは？、埋め込みとチャットはインタラクティブマップを埋め込む方法とMapbox、Google Maps、MapLibre に AI チャットを追加を参照してください。

認証の要点

• 実行環境を先に考える： ブラウザ認証情報は公開、サーバー認証情報は秘匿を前提に設計します。
• オリジン ≠ 認証： CORS と許可オリジンは認証情報の確認に代わりません。
• スコープ ≠ テナント： API 機能スコープはユーザーや行の認可ではありません。
• 安全にローテーション： 有効なキーを失効させる前に代替を配備します。
• ログを秘匿化： キー ID と状態コードだけを記録し、値は記録しません。

ブラウザのマップ API 認証はなぜ異なる？

ブラウザは信頼できない実行環境です。配信したものは、ソース、開発者ツール、ネットワーク要求、バンドル済み JavaScript、ストレージ、実行時オブジェクトから通常確認できます。長期サーバー秘密鍵を React ソース、Next.js の NEXT_PUBLIC_*、Vite の VITE_*、HTML、モバイル WebView、フロントエンド JSON に置くのは危険です。ブラウザは利用者から秘密を隠せません。どこに隠すかではなく、認証情報が何をでき、どこで実行できるかを問います。

名称は異なってもパターンは共通です。Kaleidr は公開可能キーとサーバーキーを使います（Auth & Scopes）。Mapbox は公開／秘密トークンスコープを分け、秘密トークンの要求はサーバーから行うよう説明しています（Mapbox を安全に使う）。Google Maps Platform はアプリと API の制限を使い、Web サービス認証情報の保護と、対応時のサーバー間 OAuth 2.0 を推奨します（セキュリティガイド）。

Kaleidr の公開可能キーとサーバーキーはどう動く？

現在の文書は、同じ組織・機能システムに 2 種類のキーを定義します。kld_pk_live_… は HTML、SDK、<kaleidr-map>、ブラウザ統合で使います。SDK はこの文字列を常設 bearer とせず、実行時にオリジンに紐づく短期セッションへ交換します。kld_sk_live_… は信頼できるサーバーだけで、通常 Authorization: Bearer … または X-Api-Key: … として使います。ブラウザでは拒否され、CORS 許可もありません（CORS & Allowed Origins）。サーバーキーをクライアントに置かず、公開環境変数を秘密保管庫と考えないでください。

許可オリジンはパスや末尾スラッシュを含まない https://app.example.com の形式で、https://app.example.com/maps ではありません。Kaleidr は localhost と 127.0.0.1 のローカル試験を除き HTTPS を要求します。ルート、www、app、admin、preview は別オリジンです。オリジン制限は不正再利用を減らしますが、サーバー秘密鍵をクライアントから除外する代わりにはなりません。

CORS、認証、スコープ、アプリ認可の違いは？

CORS はブラウザが別オリジン応答を読めるかを制御し、認証は呼び出し元を識別します。スコープ認可は認証情報が機能を使えるかを判断し、ホストアプリの認可はどのユーザー／テナントが非公開レコードにアクセスできるかを決めます。Kaleidr は preflight を許可しても、許可オリジンにだけ Access-Control-Allow-Origin を返し、サーバーキーにブラウザ CORS を与えません。401 は通常、認証情報の欠落、無効、期限切れ、失効です。403 は有効だが権限不足で、必要機能がない場合は insufficient_scope を使います。診断と監視では別の失敗として扱います。

認証情報をどう作成、保存、ローテーション、失効する？

最小権限を適用し、統合に必要なスコープだけを与えます。Mapbox は最小スコープとブラウザでの公開スコープのみの利用を、Google は実際に使う API だけへの制限を推奨します。開発、プレビュー、本番で 1 つのキーを共有せず、影響範囲を狭めて安全にローテーションできるよう分けます。Mapbox は環境／クライアントごとのトークン、Google はアプリごとのキーを推奨します（トークン管理）。

新しい Kaleidr キー値は一度しか表示されないため、すぐ Secret Manager に保存します。サーバーキーを公開リポジトリやブラウザバンドルに置かないでください。CI/CD では配備時に注入し、ログでマスクし、環境ダンプを出力しません。キー ID、状態、オリジンを記録し、Authorization ヘッダーと値は秘匿化します。代替キーを作成・制限・配備し、トラフィックを確認してから旧キーを失効します。侵害時は迅速に行います。クォータも安全制御で、Platform API は組織単位で計測し、ストリーミングは同時実行を制限します（Quota & Rate Limits）。429 は 401/403 と分け、再試行嵐ではなくバックオフします。

// Unsafe: never ship a server key to the browser
const SERVER_KEY = "YOUR_KALEIDR_SERVER_KEY";

// Safer browser pattern: publishable key + SDK session exchange
Kaleidr.mount("#map", {
  publishableKey: "kld_pk_live_REPLACE_ME"
});

// Safer backend pattern: server key stays on the host
const response = await fetch("https://api.example.com/resource", {
  headers: {
    Authorization: `Bearer ${process.env.KALEIDR_SERVER_KEY}`
  }
});

本番アプリでプラットフォーム認証とホスト認証をどう分ける？

推奨構成では、ブラウザは許可オリジンから公開可能キーで公開 SDK 機能を使い、認証済み製品要求はホストのバックエンドへ送ります。バックエンドはユーザー ID、テナント所属、オブジェクト認可、非公開位置データ、Secret Manager 内のサーバーキーを管理し、サーバー間で空間プラットフォームを呼び、許可した項目だけ返します。公開可能キーはエンドユーザー認証ではなく、サーバーキーは DB 行認可ではありません。公開 Viewer マップは共有リンクで保護され API キー不要と文書化されていますが、共有リンクもアクセス制御として扱い、無制限の公開ビューで非公開データを送らないでください。CSP と安全な HTML 表示も有効です。Mapbox は信頼できない HTML のポップアップ挿入による XSS を警告し、テキスト表示を推奨します。

チームが避けるべき誤りは？

ブラウザ統合の失敗時はオリジン表記、HTTPS、キー種別、スコープ、セッション交換順を確認します。サーバーでは種別、環境、スコープ、秘密注入、ローテーション時の誤失効を確認します。

最終評価

マップ API セキュリティは、ブラウザとバックエンドで同じ認証情報モデルを使わないという判断から始まります。ブラウザにはオリジン、スコープ、セッション期限などで制限した公開可能な認証情報、バックエンドには信頼できる基盤内の秘密が必要です。さらに最小権限、環境分離、アプリ認可、監視、ローテーションを重ねます。Kaleidr の公開可能キーはオリジン制限され短期セッションへ交換され、サーバーキーはサーバー間 bearer としてブラウザで拒否されます。フロントエンド内でキーを隠そうとするより、この境界が重要です。

Kaleidr 文書でマップ API を保護する

配備前にキー種別、機能スコープ、オリジン規則、API 動作を確認してください。Kaleidr Auth & Scopes を読む。SDK と Platform API ルートは開発者向け文書にあります。

よくある質問

マップ API 認証とは？

地図、場所、タイル、経路、空間 API へのアクセスを要求するアプリやサービスを識別する仕組みです。API キー、アクセストークン、セッション、bearer トークン、OAuth などがあります。

API キーをブラウザで安全に使える？

提供者がクライアント用に設計した場合だけです。許可オリジン、公開スコープ、アプリ制限、短期セッション交換が必要です。サーバー秘密鍵は置けません。

公開可能 API キーは秘密？

いいえ。文字列の秘匿に安全性を依存させませんが、制限と監視は必要です。

サーバー API キーは秘密？

はい。信頼できるバックエンドに置き、HTML、JavaScript、WebView、公開リポジトリ、クライアントストレージに含めません。

CORS は認証？

いいえ。CORS は別オリジン応答を読めるか、認証は呼び出し元、認可は可能な操作を決めます。

401 と 403 の違いは？

401 は通常、認証情報の欠落、無効、期限切れ、失効です。403 は有効でも操作権限がない状態です。

開発と本番でキーを分けるべき？

はい。影響範囲を狭め、制限と利用把握を簡単にし、ローテーションを安全にします。

API キーをどうローテーションする？

代替を作成・制限・配備し、本番トラフィックを確認後に旧キーを失効します。侵害中なら急いでください。

Kaleidr Viewer に API キーは必要？

現在の文書では、公開 Viewer マップは共有リンクで保護され、API キーは不要です。

Kaleidr はブラウザ統合をどう保護する？

許可オリジン付き公開可能キーを SDK がオリジンに紐づく短期セッションへ交換します。サーバーキーはブラウザで拒否され、サーバー間呼び出し専用です。

参考文献

• IETF. HTTP Semantics (RFC 9110). RFC Editor. 2026年8月17日参照. https://www.rfc-editor.org/rfc/rfc9110

• IETF. The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). RFC Editor. 2026年8月17日参照. https://www.rfc-editor.org/rfc/rfc6750

• WHATWG. Fetch Standard. 2026年8月17日参照. https://fetch.spec.whatwg.org/#http-cors-protocol

• Google。Google Maps Platform セキュリティガイド。2026年8月17日参照。https://developers.google.com/maps/api-security-best-practices

• Kaleidr。Auth & Scopes。Kaleidr 開発者向け文書。2026年8月17日参照。https://docs.kaleidr.com/platform-api/auth-and-scopes

• Kaleidr。CORS & Allowed Origins。Kaleidr 開発者向け文書。2026年8月17日参照。https://docs.kaleidr.com/platform-api/cors-and-allowed-origins

• Kaleidr。Quota & Rate Limits。Kaleidr 開発者向け文書。2026年8月17日参照。https://docs.kaleidr.com/platform-api/quota-and-rate-limits

• Mapbox。Mapbox を安全に使う。2026年8月17日参照。https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/

• Mapbox。トークン管理。2026年8月17日参照。https://docs.mapbox.com/accounts/guides/tokens/

@misc{ietf_rfc9110_2026,
  title  = {HTTP Semantics (RFC 9110)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc9110}
}

@misc{ietf_rfc6750_2026,
  title  = {The OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750)},
  author = {{IETF}},
  note   = {Accessed 17 August 2026},
  url    = {https://www.rfc-editor.org/rfc/rfc6750}
}

@misc{whatwg_fetch_cors_2026,
  title  = {Fetch Standard},
  author = {{WHATWG}},
  note   = {CORS protocol; accessed 17 August 2026},
  url    = {https://fetch.spec.whatwg.org/#http-cors-protocol}
}

@misc{kaleidr_auth_scopes_2026,
  title  = {Auth and Scopes},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}

@misc{kaleidr_cors_origins_2026,
  title  = {CORS and Allowed Origins},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/cors-and-allowed-origins}
}

@misc{kaleidr_quota_2026,
  title  = {Quota and Rate Limits},
  author = {{Kaleidr}},
  note   = {Kaleidr Developer Docs; accessed 17 August 2026},
  url    = {https://docs.kaleidr.com/platform-api/quota-and-rate-limits}
}

@misc{mapbox_token_management_2026,
  title  = {Token Management},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/accounts/guides/tokens/}
}

@misc{mapbox_secure_2026,
  title  = {How to Use Mapbox Securely},
  author = {{Mapbox}},
  note   = {Accessed 17 August 2026},
  url    = {https://docs.mapbox.com/help/dive-deeper/how-to-use-mapbox-securely/}
}

@misc{google_maps_security_2026,
  title  = {Google Maps Platform Security Guidance},
  author = {{Google}},
  note   = {Accessed 17 August 2026},
  url    = {https://developers.google.com/maps/api-security-best-practices}
}