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

アカウントは、業界標準の OAuth 2.0 インプリシット フローと認可コードフローを使用してリンクされます。サービスは、OAuth 2.0 準拠の認可エンドポイントとトークン交換エンドポイントをサポートする必要があります。

暗黙的フローでは、Google がデベロッパーのブラウザで認可エンドポイントを開きます。ログインに成功したら、認可エンドポイントから長期のアクセス トークンを Google に返します。このアクセス トークンは、Google から送信されるすべてのリクエストに含まれます。

認証コードフローでは、次の 2 つのエンドポイントが必要になります。

  • 認可エンドポイント。ログインしていないユーザーにログイン用の UI を表示します。認可エンドポイントは、リクエストされたアクセスに対するユーザーの同意を記録するために、有効期間の短い認可コードも作成します。

  • トークン交換エンドポイント。次の 2 種類の交換を行います。

    1. 長期の更新トークンと短期のアクセス トークンの認可コードを交換します。この処理は、ユーザーがアカウントのリンクフローを行ったときに発生します。
    2. 長期の更新トークンを短期のアクセス トークンと交換します。この処理は、トークンが期限切れになり、新しいアクセス トークンが必要になった場合に発生します。

OAuth 2.0 フローを選択する

暗黙的フローの実装は簡単ですが、暗黙的フローによって発行されたアクセス トークンには有効期限を設定しないことをおすすめします。これは、暗黙的フローでトークンが期限切れになると、ユーザーがアカウントを再度リンクしなければならないためです。セキュリティ上の理由からトークンに有効期限を設定する必要がある場合は、代わりに認可コードフローを使用することを強くおすすめします。

設計ガイドライン

このセクションでは、OAuth リンクフロー用にホストするユーザー画面の設計要件と推奨事項について説明します。Google のアプリから呼び出されると、プラットフォームはユーザーに Google にログインするページとアカウントのリンクに関する同意画面を表示します。アカウントのリンクに同意すると、ユーザーは Google のアプリに戻されます。

この図は、ユーザーが自身の Google アカウントをデベロッパーの認証システムにリンクする手順を示しています。最初のスクリーンショットは、プラットフォームからユーザーが開始するリンクを示しています。2 つ目の画像は Google へのユーザーのログインを示しています。3 つ目の画像は、Google アカウントとアプリをリンクすることに対するユーザーの同意と確認を示しています。最後のスクリーンショットは、Google アプリでユーザー アカウントが正常にリンクされた状態を示しています。
図 1. アカウント リンクのユーザーが Google にログインする画面と同意画面。

要件

  1. ユーザーのアカウントは、Google Home や Google アシスタントなどの特定の Google プロダクトではなく、Google にリンクされることを伝える必要があります。

推奨事項

次のことをおすすめします。

  1. Google のプライバシー ポリシーを表示する。同意画面に Google のプライバシー ポリシーへのリンクを含めます。

  2. 共有するデータ。明確で簡潔な表現を使用して、Google に必要なデータとその理由をユーザーに伝えます。

  3. 行動を促す明確なフレーズ同意画面に「同意してリンク」など、わかりやすい行動を促すフレーズを表示します。これは、アカウントをリンクするために Google と共有する必要があるデータをユーザーが理解する必要があるためです。

  4. キャンセルできること。ユーザーがリンクしないことを選択した場合に、ユーザーが戻るまたはキャンセルできる方法を提供します。

  5. ログイン プロセスを明確にする。ユーザーが Google アカウントにログインするための明確な方法（ユーザー名とパスワードのフィールド、Google でログインなど）があることを確認します。

  6. リンクを解除できること。ユーザーがリンクを解除するためのメカニズム（プラットフォームのアカウント設定への URL など）を提供します。または、ユーザーがリンクされたアカウントを管理できる Google アカウントへのリンクを含めることもできます。

  7. ユーザー アカウントを変更する機能。ユーザーがアカウントを切り替える方法を提案します。これは、ユーザーが複数のアカウントを持っている場合に特に便利です。

    • ユーザーがアカウントを切り替えるために同意画面を閉じる必要がある場合は、回復可能なエラーを Google に送信して、ユーザーが OAuth リンクと暗黙的フローを使用して目的のアカウントにログインできるようにします。

  8. ロゴを含めます。同意画面に会社のロゴを表示します。 スタイル ガイドラインに沿ってロゴを配置します。Google のロゴも表示する場合は、ロゴと商標をご覧ください。

创建项目

如需创建使用账号关联的项目，请执行以下操作：

  2. 点击 Create project。
  3. 输入名称或接受生成的建议。
  4. 确认或修改所有剩余字段。
  5. 点击创建。

如需查看项目 ID，请执行以下操作：

  2. 在着陆页的表格中找到您的项目。项目 ID 会显示在 ID 列中。

Google 账号关联流程包含一个权限请求页面，该页面会告知用户哪个应用在请求访问其数据、请求访问哪些类型的数据，以及适用的条款。您需要先配置 OAuth 权限请求页面，然后才能生成 Google API 客户端 ID。

  1. 打开 Google API 控制台的 OAuth 同意屏幕页面。
  2. 如果出现提示，请选择您刚刚创建的项目。

  3. 在“OAuth 同意屏幕”页面上，填写表单，然后点击“保存”按钮。

    应用名称：征求用户同意的应用的名称。名称应准确反映您的应用，并与用户在其他位置看到的应用名称保持一致。应用名称将显示在账号关联权限请求界面上。

    应用徽标：权限请求页面上显示的一张图片，用以让用户认出您的应用。徽标会显示在账号关联权限请求页面和账号设置中

    支持电子邮件地址：供用户就其同意问题与您联系。

    Google API 的范围：借助范围，您的应用可以访问用户的非公开 Google 数据。对于 Google 账号关联使用情形，默认范围（电子邮件地址、个人资料、openid）就足够了，您无需添加任何敏感范围。一般来说，最佳做法是在需要访问权限时逐步请求权限范围，而不是提前请求。了解详情。

    已获授权的网域：为了保护您和您的用户，Google 只允许使用 OAuth 进行身份验证的应用使用已获授权的网域。应用的链接必须托管在已获授权的网域上。了解详情。

    应用首页链接：应用的首页。必须托管在已获授权的网域上。

    应用隐私权政策链接：显示在 Google 账号关联意见征求界面上。必须托管在已获授权的网域上。

    应用服务条款链接（可选）：必须托管在已获授权的网域上。

    图 1. 虚构应用 Tunery 的 Google 账号关联意见征求界面

  4. 查看“验证状态”，如果您的应用需要验证，请点击“提交以供验证”按钮，提交应用以供验证。如需了解详情，请参阅 OAuth 验证要求。

OAuth サーバーを実装する

为了支持 OAuth 2.0 隐式流，您的服务会进行授权 端点。此端点负责进行身份验证， 就数据访问征得用户同意。授权端点 向尚未登录的用户显示登录界面，并记录 同意所请求的访问。

当 Google 应用需要调用您的某项服务获得授权的 API 时， Google 使用此端点从您的用户处获取调用这些 API 的权限 。

由 Google 发起的典型 OAuth 2.0 隐式流会话具有以下特征： 以下流程：

  1. Google 会在用户的浏览器中打开您的授权端点。通过 如果用户尚未登录，则直接登录，然后授予 Google 以下权限： 访问您的 API 访问其数据（如果尚未授权）。
  2. 您的服务会创建一个访问令牌并将其返回给 Google。为此，请将用户的浏览器重定向回 Google，并提供相应的访问权限 令牌。
  3. Google 调用您的服务的 API，并附加带有 。您的服务会验证访问令牌是否向 Google 授予 访问 API 的授权，然后完成 API 调用。

处理授权请求

当 Google 应用需要通过 OAuth 2.0 执行账号关联时 隐式流程，Google 会通过 请求，其中包含以下参数：

授权端点参数
client_id 您分配给 Google 的客户 ID。
redirect_uri 此请求的响应发送到的网址。
state 将一个在 重定向 URI。
response_type 要在响应中返回的值的类型。对于 OAuth 2.0 隐式 则响应类型始终为 token。
user_locale “Google 账号语言设置” RFC5646 用于将您的内容本地化为用户首选语言的格式。

例如，如果您的授权端点位于 https://myservice.example.com/auth 时，请求可能如下所示：

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

为了让授权端点能够处理登录请求，请执行以下操作 步骤：

  1. 验证 client_id 和 redirect_uri 值， 防止向意外或配置错误的客户端应用授予访问权限：

    • 确认 client_id 是否与您的客户端 ID 匹配 分配给 Google。
    • 确认 redirect_uri 指定的网址 参数的格式如下： 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  2. 检查用户是否已登录您的服务。如果用户未登录 中，完成服务的登录或注册流程。

  3. 生成访问令牌，以供 Google 用于访问您的 API。通过 访问令牌可以是任何字符串值，但必须唯一地表示 令牌对应的用户和客户端，且不得被猜到。

  4. 发送 HTTP 响应，将用户浏览器重定向到相应网址 由 redirect_uri 参数指定。添加所有 以下参数：

    • access_token：您刚刚生成的访问令牌
    • token_type：字符串 bearer
    • state：原始状态的未修改状态值 请求

    以下是生成的网址示例： 

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google 的 OAuth 2.0 重定向处理程序收到访问令牌并确认 state 值没有更改。在 Google 获得 访问令牌，则 Google 会将该令牌附加到后续调用 服务 API

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 Unauthorized またはその他の失敗したエラー レスポンスが返された場合、そのエラーは修復不能となり、取得したトークンは破棄されるため、ユーザーはリンク処理をやり直す必要があります。

  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 字段中，选择 Client-side（客户端）。
  3. 在 OAuth 端点字段中，选择自定义。
  4. 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
  5. 在第 1 步部分，不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围（如果您不使用 OAuth 范围，则可以输入任意字符串）。完成后，点击授权 API。
  6. 在 Step 2 和 Step 3 部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

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

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

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