OAuth による Google アカウントのリンク

アカウントは、業界標準の OAuth 2.0 認可コードフローを使用してリンクされます。

エージェント向けの OAuth 2.1 と PKCE

ステートレス AI エージェントとマルチモーダル パイプラインには、OAuth 2.1 の適用をおすすめします。

  • PKCE（Proof Key for Code Exchange）: 認可コードフローを保護し、傍受攻撃を防ぐために使用する必要があります。
  • 暗黙的フローなし: 暗黙的フローでは、アクセス トークンが URL に公開されるため、エージェント環境でセキュリティ リスクが生じます。

サービスは、OAuth 2.0/2.1 準拠の認可エンドポイントとトークン 交換エンドポイントをサポートする必要があります。

プロジェクトを作成する

アカウント リンクを使用するプロジェクトを作成するには:

  1. Google API コンソールに移動します。
  2. [プロジェクトの作成] をクリックします。
  3. 名前を入力するか、生成された候補を受け入れます。
  4. 残りのフィールドを確認または編集します。
  5. [作成] をクリックします。

プロジェクト ID を表示するには:

  1. Google API コンソールに移動します。
  2. ランディング ページの表でプロジェクトを探します。プロジェクト ID は [ID] 列に表示されます。

Google アカウントのリンク プロセスには同意画面が含まれています。この画面では、データへのアクセスをリクエストしているアプリケーション、リクエストしているデータの種類、適用される規約がユーザーに通知されます。Google API クライアント ID を生成する前に、OAuth 同意画面を構成する必要があります。

  1. Google API コンソールの OAuth 同意画面 ページを開きます。
  2. プロンプトが表示されたら、作成したプロジェクトを選択します。

  3. [OAuth 同意画面] ページでフォームに入力し、[保存] ボタンをクリックします。

    アプリケーション名: 同意を求めるアプリケーションの名前。名前はアプリケーションを正確に反映し、ユーザーが他の場所で見るアプリケーション名と一致している必要があります。アプリケーション名は、アカウント リンクの同意画面に表示されます。

    アプリケーション ロゴ: 同意画面に表示される画像で、ユーザーがアプリを認識しやすくなります。ロゴは、アカウント リンクの同意画面とアカウント設定に表示されます。

    サポートメール: 同意に関して問い合わせる際に使用します。

    Google API のスコープ: スコープを使用すると、アプリケーションはユーザーの非公開の Google データにアクセスできます。Google アカウントのリンクのユースケースでは、デフォルトのスコープ（email、profile、openid）で十分です。機密性の高いスコープを追加する必要はありません。一般的に、スコープは事前にリクエストするのではなく、アクセスが必要になったときに段階的にリクエストすることが効果的な手法です。詳細

    承認済みドメイン: デベロッパーとユーザーを保護するために、Google では、OAuth を使用して認証するアプリケーションのみに承認済みドメインの使用を許可しています。アプリケーションのリンクは、承認済みドメインでホストする必要があります。詳細

    アプリケーションのホームページへのリンク: アプリケーションのホームページ。承認済みドメインでホストする必要があります。

    アプリケーションのプライバシー ポリシーへのリンク: Google アカウント リンクの同意画面に表示されます。承認済みドメインでホストする必要があります。

    アプリケーションの利用規約へのリンク（省略可）: 承認済みドメインでホストする必要があります。

    図 1. 架空のアプリケーション Tunery の Google アカウントのリンクの同意画面

  4. [検証ステータス] を確認します。アプリケーションの検証が必要な場合は、[検証のために送信] ボタンを**クリック**して、検証を受けるためにアプリケーションを送信します。詳しくは、OAuth の検証要件をご覧ください。

OAuth サーバーを実装する

認可コードフローの OAuth 2.0 サーバーは 2 つのエンドポイントで構成されます。これらのエンドポイントには HTTPS 経由でアクセスできます。 最初のエンドポイントは、データアクセスに対するユーザーの同意を検索または取得する役割を担う認証エンドポイントです。認可エンドポイントは、ログインしていないユーザーにログイン用の UI を表示し、リクエストされたアクセスへの同意を記録します。2 つ目のエンドポイントはトークン交換エンドポイントで、トークンという暗号化された文字列を取得し、ユーザーにサービスへのアクセスを許可します。

Google アプリケーションでサービスの API を呼び出す必要がある場合、Google はこれらのエンドポイントを使用して、API の呼び出し許可をユーザーから取得します。

Google アカウントのリンク: OAuth 認可コードフロー

次のシーケンス図は、ユーザー、Google、サービスの各エンドポイント間のインタラクションの詳細を示しています。

ユーザー Google アプリ / ブラウザ Google サーバー 認可 エンドポイント トークン エンドポイント 1. ユーザーがリンクを開始 2. 認可エンドポイントにリダイレクト（GET） client_id、redirect_uri、state、scope 3. ログイン画面と同意画面を表示 4. ユーザーが認証して同意を付与 5. Google にリダイレクト（GET） code, state 6. リダイレクトを処理してコード/状態を渡す 7. トークン交換（POST） grant_type=authorization_code、code 8. トークンを返す（200 OK） access_token、refresh_token 9. ユーザー トークンを保存 10. ユーザーリソースにアクセス
図 1.Google アカウントのリンクの OAuth 2.0 認可コードフローのイベント シーケンス。

役割と責任

次の表に、Google アカウントのリンク（GAL）OAuth フローのアクターの役割と責任を示します。GAL では、Google が OAuth クライアントとして機能し、サービスが ID/サービス プロバイダとして機能します。

アクター / コンポーネント GAL ロール 責任
Google アプリ / サーバー OAuth クライアント フローを開始し、認証コードを受け取ってトークンと交換し、安全に保存してサービスの API にアクセスします。
認可エンドポイント 認可サーバー ユーザーを認証し、データへのアクセスを Google と共有することへの同意を得ます。
トークン交換エンドポイント 認可サーバー 認可コードと更新トークンを検証し、Google サーバーにアクセス トークンを発行します。
Google リダイレクト URI コールバック エンドポイント 認可サービスからユーザー リダイレクトを受け取り、 code 値と state 値を取得します。

Google が開始する OAuth 2.0 認可コードフローのセッションは次のような流れになります。

  1. Google がユーザーのブラウザで認可エンドポイントを開きます。アクションのフローが音声専用デバイスで開始した場合、Google は実行をスマートフォンに転送します。
  2. ユーザーがログインし（ログインしていない場合）、Google が API を使用してデータにアクセスすることを承諾します（まだ許可していない場合）。
  3. サービスが認証コードを作成し、その認証コードを Google に返します。
  4. Google が認可コードをトークン交換エンドポイントに送信します。このエンドポイントでコードの真正性が検証され、アクセス トークンと更新トークンが返されます。アクセス トークンは短期のトークンで、API にアクセスするための認証情報として使用されます。更新トークンは長期のトークンで、Google が保存してアクセス トークンが期限切れになったときに新しいトークンを取得するために使用できます。
  5. ユーザーがアカウント リンクフローを完了すると、それ以降 Google から送信されるすべてのリクエストにアクセス トークンが含まれます。

実装レシピ

認可コードフローを実装する手順は次のとおりです。

ステップ 1: 認可リクエストを処理する

Google がアカウント リンクを開始すると、ユーザーは認可エンドポイントにリダイレクトされます。プロトコルの詳細な契約とパラメータ要件については、認可エンドポイントをご覧ください。

リクエストを処理する手順は次のとおりです。

  1. リクエストを検証する:

    • client_id が Google に割り当てたクライアント ID と一致することを確認します。
    • redirect_uri が想定される Google リダイレクト URL: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID と一致することを確認します。
    • response_type が code であることを確認します。

  2. ユーザーを認証する:

    • ユーザーがサービスにログインしているかどうか確認します。
    • ユーザーがログインしていない場合は、ログインまたは登録フローを完了するように促します。

  3. 認証コードを生成する:

    • ユーザーとクライアントに関連付けられた、推測できない一意の認証コードを作成します。
    • コードの有効期限を約 10 分に設定します。

  4. Google にリダイレクトする:

    • ブラウザを redirect_uri で指定された URL にリダイレクトします。
    • 次のクエリ パラメータを追加します。
      • code: 生成した認証コード。
      • state: Google から受け取った変更されていない状態値。

ステップ 2: トークン交換リクエストを処理する

トークン交換エンドポイントは、コードとトークンの交換と、期限切れのアクセス トークンの更新という、2 種類のリクエストを処理します。プロトコルの詳細な契約とパラメータ要件については、トークン交換エンドポイントをご覧ください。

A. 認可コードをトークンと交換する

Google が認証コードを受け取ると、トークン交換エンドポイント（POST）を呼び出してトークンを取得します。

  1. リクエストを検証する:

    • client_id と client_secret を確認します。
    • 認証コードが有効で、期限切れになっていないことを確認します。
    • redirect_uri がステップ 1 で使用した値と一致することを確認します。
    • 検証に失敗した場合は、{"error": "invalid_grant"} を含む HTTP 400 Bad Request を返します。

  2. トークンを発行する:

    • 有効期間の長い refresh_token と有効期間の短い access_token（通常は 1 時間）を生成します。
    • 標準の JSON トークン レスポンスを含む HTTP 200 OK を返します。

B. アクセス トークンを更新する

アクセス トークンの有効期限が切れると、Google は更新トークンを使用して新しいトークンをリクエストします。

  1. リクエストを検証する:

    • client_id、client_secret、refresh_token を確認します。
    • 検証に失敗した場合は、{"error": "invalid_grant"} を含む HTTP 400 Bad Request を返します。

  2. 新しいアクセス トークンを発行する:

    • 有効期間の短い新しい access_token を生成します。
    • JSON トークン レスポンス（必要に応じて新しい更新トークンを含む）を含む HTTP 200 OK を返します。
处理 userinfo 请求

userinfo 端点是受 OAuth 2.0 保护的资源，会返回关联用户的声明。实现和托管 userinfo 端点是可选的，但以下用例除外：

从您的令牌端点成功检索到访问令牌后，Google 会向您的 userinfo 端点发送请求，以检索关联用户的基本个人资料信息。

userinfo 端点请求标头
Authorization header Bearer 类型的访问令牌。

例如，如果您的 userinfo 端点可通过 https://myservice.example.com/userinfo 时，请求可能如下所示：

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

为了让 userinfo 端点能够处理请求，请执行以下步骤：

  1. 从 Authorization 标头中提取访问令牌，并返回与访问令牌相关联的用户的信息。
  2. 如果访问令牌无效，则使用 WWW-Authenticate 响应标头返回 HTTP 401 Unauthorized 错误。下面是一个 userinfo 错误响应示例： 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    如果在关联过程中返回 401 未经授权错误或任何其他失败的错误响应，该错误将无法恢复，检索到的令牌将被舍弃，并且用户必须重新开始关联流程。

  3. 如果访问令牌有效，则返回 HTTPS 正文中包含以下 JSON 对象的 HTTP 200 响应 回答：

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     如果您的 userinfo 端点返回 HTTP 200 成功响应，则系统会针对用户的 Google 账号注册检索到的令牌和声明。

    userinfo 端点响应
    sub 系统中用于识别用户的唯一 ID。
    email 用户的电子邮件地址。
    given_name 可选：用户的名字。
    family_name 可选：用户的姓氏。
    name 可选：用户的全名。
    picture 可选：用户的个人资料照片。

実装の検証

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

在该工具中，执行以下步骤：

  1. 点击配置 以打开“OAuth 2.0 配置”窗口。
  2. 在 OAuth flow（OAuth 流程）字段中，选择 Client-side（客户端）。
  3. 在 OAuth Endpoints 字段中，选择 Custom。
  4. 在相应字段中指定您的 OAuth 2.0 端点以及您分配给 Google 的客户端 ID。
  5. 在第 1 步部分中，请勿选择任何 Google 范围。请将此字段留空，或输入适用于您服务器的范围（如果您不使用 OAuth 范围，则输入任意字符串）。完成后，点击 Authorize APIs。
  6. 在第 2 步和第 3 步部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示工具验证您的实现。

在该工具中，执行以下步骤：

  1. 点击使用 Google 账号登录按钮。
  2. 选择您要关联的账号。
  3. 输入服务 ID。
  4. （可选）输入您将请求访问的一个或多个范围。
  5. 点击开始演示。
  6. 当系统提示时，请确认您可以同意或拒绝关联请求。
  7. 确认您已重定向到相应平台。