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

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

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

在隐式流程中，Google 会在用户的浏览器中打开您的授权端点。成功登录后，您会向 Google 返回长期有效的访问令牌。此访问令牌现在包含在 Google 发送的每个请求中。

在 授权代码 流程中，您需要两个端点：

授权端点，用于向尚未登录的用户显示登录界面。授权端点还会创建一个短期有效的授权代码，以记录用户对所请求访问权限的同意情况。
令牌交换 端点，负责两种类型的交换：
1. 将授权代码交换为长期有效的刷新令牌和短期有效的访问令牌。当用户完成账号关联流程时，会发生此交换。
2. 将长期有效的刷新令牌交换为短期有效的访问令牌。当 Google 需要新的访问令牌（因为其拥有的访问令牌已过期）时，会发生此交换。

选择 OAuth 2.0 流程

虽然隐式流程的实现较为简单，但 Google 建议通过隐式流程颁发的访问令牌永不过期。这是因为，如果令牌通过隐式流程过期，用户就必须再次关联其账号。如果您出于安全原因需要令牌过期，我们强烈建议您改用 授权代码 流程。

设计准则

本部分介绍了您为 OAuth 关联流程托管的用户界面的设计要求和建议。在 Google 的应用调用后，您的平台会向用户显示“登录 Google”页面和账号关联同意屏幕。用户同意关联账号后，系统会将用户重定向回 Google 的应用。

此图显示了用户将其 Google 账号与您的身份验证系统相关联的步骤。第一个屏幕截图显示了用户从您的平台发起的关联。第二张图片显示了用户登录 Google 的界面，第三张图片显示了用户同意并确认将自己的 Google 账号与您的应用相关联的界面。最后一张屏幕截图显示了 Google 应用中成功关联的用户账号。 — **图 1.**账号关联用户登录 Google 和同意屏幕。

要求

您必须说明，用户的账号将与 Google 关联， 而不是与 Google Home 或 Google 助理等特定 Google 产品关联。

建议

建议您执行以下操作：

显示 Google 的隐私权政策。在权限请求页面上添加指向 Google 的隐私权政策的链接。
要共享的数据。 使用清晰简洁的语言告知用户 Google 需要哪些数据及其原因。
明确的号召性用语。 在同意屏幕上添加明确的号召性用语，例如“同意并关联”。这是因为用户需要了解他们需要与 Google 共享哪些数据才能关联其账号。
能够取消。 为用户提供返回或取消的方式（如果他们选择不关联）。
清晰的登录流程。 确保用户有清晰的 Google 账号登录方法，例如用户名和密码字段，或 “使用 Google 账号登录”。
能够取消关联。 为用户提供取消关联的机制，例如指向您平台上账号设置的网址。或者，您可以添加指向 Google 账号的链接，用户可以在其中管理其关联的账号。
能够更改用户账号。 为用户提供切换账号的方法。如果用户倾向于拥有多个账号，这一点尤其有用。
- 如果用户必须关闭权限请求页面才能切换账号，请向 Google 发送可恢复的错误，以便用户可以使用 OAuth 关联 和隐式流程登录所选账号。
添加您的徽标。 在权限请求页面上显示您的公司徽标。请按照您的样式指南放置徽标。如果您想要或需要同时显示 Google 的徽标，请参阅徽标和商标。

プロジェクトを作成する

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

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

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

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

OAuth 同意画面を構成する

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

Google API コンソールの OAuth 同意画面ページを開きます。
プロンプトが表示されたら、作成したプロジェクトを選択します。
[OAuth 同意画面] ページでフォームに入力し、[保存] ボタンをクリックします。

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

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

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

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

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

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

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

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

図 1. 架空のアプリケーション Tunery の Google アカウントのリンクの同意画面
[検証ステータス] を確認します。アプリケーションの検証が必要な場合は、[検証のために送信] ボタンを**クリック**して、検証を受けるためにアプリケーションを送信します。詳しくは、OAuth の検証要件をご覧ください。

OAuth サーバーを実装する

サービスで OAuth 2.0 インプリシット フローをサポートするには、HTTPS 経由で認可エンドポイントにアクセスできるようにする必要があります。このエンドポイントは、ユーザーの認証を行い、ユーザーからデータアクセスへの同意を取得します。認可エンドポイントは、ログインしていないユーザーにログイン用の UI を表示し、リクエストされたアクセスへの同意を記録します。

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

Google アカウントのリンク: OAuth 暗黙的フロー

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

図 1. Google アカウントのリンク用の OAuth 2.0 暗黙的フローのイベントシーケンス。

役割と責任

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

アクター / コンポーネント	GAL ロール	責任
Google アプリ / サーバー	OAuth クライアント	フローを開始し、ブラウザのリダイレクトを使用してアクセストークンを受け取り、サービス API にアクセスするために安全に保存します。
認可エンドポイント	認可サーバー	ユーザーを認証し、ユーザーの同意を取得して、有効期間の長いアクセストークンを Google に直接発行します。
Google リダイレクト URI	コールバックエンドポイント	URL フラグメントに `access_token` 値と `state` 値を含む、認証サービスからのユーザーリダイレクトを受け取ります。

通常、Google が開始する OAuth 2.0 インプリシットフローのセッションは次のような流れになります。

Google がユーザーのブラウザで認可エンドポイントを開きます。ユーザーがログインし（ログインしていない場合）、Google が API を使用してデータにアクセスすることを承諾します（まだ許可していない場合）。
サービスがアクセストークンを作成し、Google に返します。そのためには、アクセストークンをリクエストに付加して、ユーザーのブラウザを Google にリダイレクトします。
Google がサービスの API を呼び出し、リクエストごとにアクセストークンを関連付けます。サービスは、アクセストークンによって API へのアクセスが Google に許可されていることを確認し、API 呼び出しを完了します。

認可リクエストの処理

Google アプリケーションで OAuth 2.0 暗黙的フローを使用してアカウントリンクを行う必要がある場合、Google は、次のパラメータを含むリクエストを使用して、ユーザーを認可エンドポイントに送信します。

認可エンドポイントのパラメータ
`client_id`	Google に割り当てたクライアント ID。
`redirect_uri`	このリクエストに対するレスポンスを送信する URL。
`state`	リダイレクト URL で変更されずに Google に返される会計上の値。
`response_type`	レスポンスで返される値のタイプ。OAuth 2.0 インプリシットフローの場合、レスポンスタイプは常に `token` です。
`user_locale`	ユーザーの優先言語でコンテンツをローカライズするために使用される、RFC5646 形式の Google アカウントの言語設定。

たとえば、認可エンドポイントが 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

認可エンドポイントでログインリクエストを処理する場合は、次の手順に従います。

意図しないクライアントアプリや誤って構成されたクライアントアプリにアクセスを許可しないように、client_id と redirect_uri の値を確認します。
- client_id が Google に割り当てたクライアント ID と一致することを確認します。
- redirect_uri パラメータで指定された URL が次の形式になっていることを確認します。
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
```
ユーザーがサービスにログインしているかどうか確認します。ユーザーがログインしていない場合は、サービスのログインまたは登録フローを完了します。
Google が API にアクセスするために使用するアクセストークンを生成します。アクセストークンには任意の文字列値を設定できますが、トークンを使用するユーザーとクライアントを一意に表し、簡単に推測されない文字列にする必要があります。
ユーザーのブラウザを redirect_uri パラメータで指定された URL にリダイレクトする HTTP レスポンスを送信します。URL フラグメントに次のパラメータをすべて含めます。
- access_token: 先ほど生成したアクセストークン
- token_type: 文字列 bearer
- state: 元のリクエストから変更されていない state 値
結果の URL の例を次に示します。
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
```

Google の OAuth 2.0 リダイレクトハンドラがアクセストークンを受け取り、state 値が変更されていないことを確認します。サービスのアクセストークンを取得した後は、サービス API に対する以降の呼び出しで、このトークンが使用されます。

userinfo リクエストを処理する

userinfo エンドポイントは、OAuth 2.0 で保護されたリソースで、リンクされたユーザーに関するクレームを返します。userinfo エンドポイントの実装とホストは任意ですが、以下のユースケースを除きます。

Google One タップによるリンクされたアカウントへのログイン。
Android TV のスムーズな定期購入。

トークンエンドポイントからアクセストークンが正常に取得されると、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 エンドポイントでリクエストを処理するには、次の手順を行います。

Authorization ヘッダーからアクセストークンを抽出し、そのアクセストークンに関連付けられたユーザーの情報を返します。
アクセストークンが無効な場合は、WWW-Authenticate レスポンスヘッダーを使用して HTTP 401 Unauthorized エラーを返します。userinfo エラーレスポンスの例を次に示します。
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
リンク処理中に 401 Unauthorized またはその他の失敗したエラーレスポンスが返された場合、そのエラーは修復不能となり、取得したトークンは破棄されるため、ユーザーはリンク処理をやり直す必要があります。

アクセストークンが有効な場合は、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 ツールを使用して、実装を検証できます。

このツールで、次の手順を行います。

[構成] 設定をクリックして、[OAuth 2.0 構成] ウィンドウを開きます。
[OAuth flow] フィールドで、[クライアントサイド] を選択します。
[OAuth Endpoints] フィールドで、[Custom] を選択します。
対応するフィールドに、OAuth 2.0 エンドポイントと Google に割り当てたクライアント ID を指定します。
[Step 1] セクションで、Google スコープを選択しないでください。代わりに、このフィールドを空白のままにするか、サーバーで有効なスコープを入力します（OAuth スコープを使用しない場合は任意の文字列を入力します）。完了したら、[Authorize APIs] をクリックします。
[Step 2] セクションと [Step 3] セクションで、OAuth 2.0 フローを確認し、各ステップが意図したとおりに動作することを確認します。

Google アカウントリンクデモツールを使用して、実装を検証できます。