OAuth 2.1 実装ガイド

このガイドでは、Connected Apps Platform がサービスに安全にアクセスできるように認可する方法について説明します。接続済みアプリの MCP 統合では、委任認可の業界標準である OAuth 2.1 と Proof Key for Code Exchange（PKCE）を使用して、ユーザーデータのセキュリティと「エージェント」フローの信頼性を最大限に高めることを強くおすすめします。Connected Apps Platform は、Proof Key for Code Exchange（PKCE）パラメータを使用した認証コード権限付与タイプをサポートしています。

PKCE は、すべての OAuth 2.1 で必須であり、OAuth 2.0 ではオプションです。

自動検出を有効にしてオンボーディング プロセスを効率化するには、認可サーバーが 認可サーバー メタデータ拡張機能（OAuth Discovery とも呼ばれます）をサポートしている必要があります。

ヒント: ユーザー エクスペリエンスの低下やアカウントの再リンクの必要性を回避するために、最も重要なことは、永続的なリンクを使用して更新トークンの有効期間を管理することです。

Gemini MCP が構成 JSON を取得する方法

Gemini MCP コンソールは、このセクションに示す順序で、次の URL から構成 JSON の取得を試みます。

注意: Gemini MCP コンソールは、レスポンス（エラーを含む）を返す最初の URL を使用します。優先エンドポイントにアクセス可能で、HTTP 200 が返されることを確認します。

認可サーバーの URL がドメインの最上位（https://auth.example.com など）にある場合、Gemini は標準の「既知の」ディレクトリをドメインに追加し、次の順序でサーバーを検索します。

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

認可サーバーの URL がドメインの特定のサブディレクトリまたはパス（https://auth.example.com/realms/master など）にある場合、Gemini は同じ「既知の」パスをそのサブディレクトリに直接追加します。

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration（ネストされたパスのサポート）

必要な JSON 機能

メタデータ レスポンスには、次のフィールドを含める必要があります。必須フィールドが欠落しているか、有効なタイプが見つからない場合、統合は失敗します。

authorization_endpoint

有効な文字列 URL を指定してください。

token_endpoint

有効な文字列 URL を指定してください。

response_types_supported

文字列 code を含める必要があります。

registration_endpoint

現時点では、Google Play Console は Dynamic Client に依存しています。

登録（RFC 7591）。メタデータに登録エンドポイントを指定するか、Google Play Console の UI でクライアント ID / シークレットを直接入力する必要があります。

認可サーバーが動的クライアント登録（DCR）をサポートしていない場合は、Google Play Console の UI で [クライアント ID] フィールドと [クライアント シークレット] フィールドを手動で実装して入力し、統合を完了する必要があります。

実装が Proof Key for Code Exchange（PKCE）または永続セッションをサポートしている場合は、検出 JSON に関連する機能フィールド（チャレンジ メソッドや権限付与タイプなど）を含める必要があります。これにより、Gemini のセキュリティ標準と接続標準との互換性を確保できます。スコープをサポートする場合は、scopes_supported フィールドを含める必要があります。

構成の例

以下は、クライアントの要件を満たす有効な JSON レスポンスです。

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

PKCE を含める場合、次のスニペットは JSON ブロックに含めることができる内容の例を示しています。

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

scopes_supported フィールドを含める場合、次のスニペットは JSON ブロックに含めることができる内容の例を示しています。

"scopes_supported": ["mcp", "cart.order"],

認可コードフロー（簡易版）

標準的な認可コードフローの手順は次のとおりです。このシーケンスは、Connected Apps Platform がユーザーに代わって動作するために必要なアクセス トークンをサーバーから安全に取得する方法を正確に示しています。

1. 認可リクエスト: Google サーフェスは、関数を呼び出す必要があると判断しますが、ユーザーはまだ認可されていません。chatbot は、ユーザーのブラウザを認可エンドポイントにリダイレクトする（またはリンクを表示する）ことで、フローを開始します。

   このリクエストには、クライアント ID（または DCR で自動生成されたもの）、Gemini のリダイレクト URI、重要な PKCE パラメータ（code_challenge と code_challenge_method）が含まれます。

   OAuth の設定で、次の URL を許可リストに登録します。

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. ユーザーの同意: 認可サーバーがリクエストを検証し、ユーザーを認証（ログイン）して、Google サーフェスにデータまたはサービスへのアクセスを許可するようユーザーに求めます。

3. コードの付与: ユーザーが同意すると、サーバーはユーザーのブラウザを Gemini の RedirectURI にリダイレクトし、URL に一時的な認証コードを追加します。

4. トークン交換: Gemini のバックエンドがトークン エンドポイントに POST リクエストを送信し、認証コードをアクセス トークンと交換します。

   注: このリクエストには、フローを開始したクライアントと同じであることを証明するために、PKCE パラメータ（code_verifier）を含める必要があります。

5. アクセス権の付与: トークン エンドポイントがコードと PKCE パラメータを検証し、アクセス トークンと（必要に応じて）更新トークンを発行して、Gemini に返します。

   ヒント: 更新トークンは省略可能ですが、更新トークンを発行するように認可サーバーを構成することを強くおすすめします。更新トークンを使用すると、Connected Apps Platform はユーザーを再認証することなくアクセスを維持できます。

PKCE の主な要件

PKCE は、認可コードの不正なインターセプトを防ぐためにセキュリティ レイヤを追加します。

注意: これらの PKCE 要件を満たすことは、アクセス トークンと更新トークンを適切に管理するために不可欠です。これにより、ユーザーデータを保護し、エコシステムの整合性を維持できます。

• code_verifier: フローの開始時に Gemini によって生成される暗号学的にランダムな文字列。この情報は非公開です。
• code_challenge: code_verifier の変換（通常は SHA256 ハッシュ）。これは、認可コードフローのステップ 1 で説明したように、公開で送信されます。
• 検証: トークン エンドポイント（認可コードフローのステップ 4 で説明）は、受信した code_verifier が変換されたときに、元の code_challenge と一致することを検証する必要があります。

デバッグ

リンクエラーの詳細情報はログ エクスプローラで確認できます。エラーを有効にして表示するには、Google Console プロジェクトでアカウント リンクエラーをモニタリングするの手順に沿って操作します。

Google アカウントのリンク設定の要件

Google アカウントのリンク設定については、次の API ガイダンスをご覧ください。

• OAuth を使用した Google アカウントのリンク
• アカウント リンク API
• Google Account Linking API

OAuth 統合を正常に登録するには、認可サーバーに関する特定の詳細を構成する必要があります。次のエンドポイント、認証情報、アセットが準備されていることを確認します。

構成フィールド	説明	デベロッパーの責任
クライアント ID とシークレット	認可サーバーが Connected Apps Platform 専用に生成する一意の認証情報。クライアント シークレットは、クライアント ID に関連付けられた安全な認証情報（パスワード）です。 注: デベロッパーがクライアント ID を発行した場合は、デベロッパーがこの情報を提供する必要があります。Google がクライアント ID を発行した場合、デベロッパーはシークレットの登録または確認が必要になることがあります。	すべての認可リクエストで、プラットフォームから提供された ID を使用します。
認可エンドポイント	ユーザーをリダイレクトして認証と同意を求める URL	エンドポイントをホストする（例: https://yourdomain.com/oauth/authorize）
トークン エンドポイント	認可コードをアクセス トークン / 更新トークンと交換し、期限切れのトークンを更新するためのバックエンド エンドポイント。	このエンドポイントをホストします（例: https://yourdomain.com/oauth/token）。
失効エンドポイント 省略可	ユーザーが接続を解除したときにトークンを無効にするようシステムに通知する URL。 ユーザーが Connected Apps Platform 内から統合のリンクを解除または切断すると、アクセス トークンまたは更新トークンを含む POST リクエストが /revoke エンドポイントに送信されます。 詳しくは、アカウントのリンク解除をご覧ください。	エンドポイントをホストする（例: https://yourdomain.com/oauth/revoke） サーバーは、提供されたトークンを完全に無効にすることで、このリクエストを処理する必要があります。これにより、Connected Apps Platform がそのトークンを使用しようとする後続の試行はすべて失敗し、接続解除後もユーザーのデータが安全に保たれます。
リダイレクト URI	同意後に認可サーバーがコードを返す、プラットフォームによって提供される特定のコールバック URL。	プラットフォームからの公式の登録済みリダイレクト URI のみを受け入れるように認可サーバーを構成します。
更新	grant_type=refresh_token で /token 現在のアクセス トークンの有効期限が切れたときに、Connected Apps Platform が新しいアクセス トークンを取得できるようにするメカニズム。ユーザーが繰り返しログインしなくても、統合をシームレスに接続したままにできます。 既存のアクセス トークンの有効期限が切れると、Connected Apps Platform は /token エンドポイントに POST リクエストを自動的に送信します。リクエスト ペイロードには、grant_type=refresh_token と、サーバーが以前に発行した更新トークンが含まれます。	サーバーは、提供された更新トークンを検証し、JSON レスポンスで新しいアクセス トークンを返す必要があります。また、永続的なリンクを実装するには、この交換中に更新トークンをローテーションしないようにする必要があります。新しい更新トークンを発行するのではなく、JSON レスポンスでまったく同じ更新トークンを返し、バックエンドで有効期限を延長します。
レスポンス タイプ	認可コードフローをサポートするには、これを CODE に構成する必要があります。
スコープ	トークンに許可される操作を定義する、特定の権限とアクセスレベルのセット。これらは、Google が最初の認可ハンドシェイク中にリクエストできるように、構成で事前に定義しておく必要があります。	フローの開始時に Connected Apps Platform がリクエストするデフォルトのスコープ（openid, profile, email など）のリストを指定する必要があります。 リクエストするスコープは、可能な限り最小限に抑える必要があります（最小権限の原則）。ただし、MCP 統合がサポートするクリティカル ユーザー ジャーニー（CUJ）に十分なスコープをリクエストする必要があります。
UI アセット: ロゴ	アカウントのリンク画面と同意画面に表示されるデベロッパーのロゴ。	円形の外観を持つ正方形のベクター画像（SVG）で、500 × 500 ピクセル以上である必要があります。たとえば、https://[partner-domain]/assets/logo.svg または未加工の SVG ファイルをご覧ください。
ネイティブ アプリのリンク（アプリ切り替え）	ネイティブの Android アプリまたは iOS アプリから直接アカウントのリンクをサポートする場合、標準の WebView を使用することはおすすめしません。代わりに、シームレスなユーザー エクスペリエンスを実現するために、アプリ切り替えを実装することを強くおすすめします。 詳しくは、OAuth ベースのアプリ切り替えを使用した Google アカウントのリンクをご覧ください。	Google Play ストアとアプリストアの確認を完了し、Google のリダイレクト URI をネイティブ アプリに直接埋め込んで、安全なアプリ間認証フリップを実現します。
トークンの存続期間	（省略可）更新が必要になるまでのアクセス トークンの有効期間。GAL でタイムアウト ポリシーを構成する場合に便利です。	一般的な有効期限は、セキュリティのニーズに応じて数分、数時間、数日などです（例: 30 days）。

統合に関する一般的なエラー

統合プロセスに適用される一般的なエラーと、考えられる解決策を以下に示します。

• 「code」権限がない: Gemini プラットフォームの自動システムは、response_types_supported で「code」値を明示的に確認します。
• 登録エンドポイントがない: サーバーがクライアント ID メタデータ ドキュメントをサポートしている場合でも、Gemini アプリ（サーバーに接続する OAuth クライアントとして機能）では、現在、ディスカバリ JSON に専用の registration_endpoint が存在する必要があります。
• 200 以外のエラー: Gemini の自動メタデータ検出メカニズムが well-known URL にアクセスして 404 または 500 を受信した場合、他の URL の推測は試行されません。Discovery URL が一般公開されていることを確認してください。