このページは Cloud Translation API によって翻訳されました。

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 にログインする画面と同意画面。

要件

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

推奨事項

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

Google のプライバシーポリシーを表示する。同意画面に Google のプライバシーポリシーへのリンクを含めます。
共有するデータ。明確で簡潔な表現を使用して、Google に必要なデータとその理由をユーザーに伝えます。
行動を促す明確なフレーズ同意画面に「同意してリンク」など、わかりやすい行動を促すフレーズを表示します。これは、アカウントをリンクするために Google と共有する必要があるデータをユーザーが理解する必要があるためです。
キャンセルできること。ユーザーがリンクしないことを選択した場合に、ユーザーが戻るまたはキャンセルできる方法を提供します。
ログインプロセスを明確にする。ユーザーが Google アカウントにログインするための明確な方法（ユーザー名とパスワードのフィールド、Google でログインなど）があることを確認します。
リンクを解除できること。ユーザーがリンクを解除するためのメカニズム（プラットフォームのアカウント設定への URL など）を提供します。または、ユーザーがリンクされたアカウントを管理できる Google アカウントへのリンクを含めることもできます。
ユーザーアカウントを変更する機能。ユーザーがアカウントを切り替える方法を提案します。これは、ユーザーが複数のアカウントを持っている場合に特に便利です。
- ユーザーがアカウントを切り替えるために同意画面を閉じる必要がある場合は、回復可能なエラーを Google に送信して、ユーザーが OAuth リンクと暗黙的フローを使用して目的のアカウントにログインできるようにします。
ロゴを含めます。同意画面に会社のロゴを表示します。スタイルガイドラインに沿ってロゴを配置します。Google のロゴも表示する場合は、ロゴと商標をご覧ください。

プロジェクトを作成する

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

[プロジェクトの作成] をクリックします。
名前を入力するか、生成された候補をそのまま使用します。
残りのフィールドを確認または編集します。
[作成] をクリックします。

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

ランディングページの表でプロジェクトを見つけます。プロジェクト ID は [ID] 列に表示されています。

OAuth 同意画面を構成する

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

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

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

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

サポートのメールアドレス: ユーザーが同意について問い合わせる際に使用します。

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

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

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

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

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

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

OAuth サーバーを実装する

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

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

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

Google 会在用户的浏览器中打开您的授权端点。通过如果用户尚未登录，则直接登录，然后授予 Google 以下权限：访问您的 API 访问其数据（如果尚未授权）。
您的服务会创建一个访问令牌并将其返回给 Google。为此，请将用户的浏览器重定向回 Google，并提供相应的访问权限令牌。
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

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

验证 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
```
检查用户是否已登录您的服务。如果用户未登录中，完成服务的登录或注册流程。
生成访问令牌，以供 Google 用于访问您的 API。通过访问令牌可以是任何字符串值，但必须唯一地表示令牌对应的用户和客户端，且不得被猜到。
发送 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 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 字段中，选择 Client-side（客户端）。
在 OAuth 端点字段中，选择自定义。
在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
在第 1 步部分，不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围（如果您不使用 OAuth 范围，则可以输入任意字符串）。完成后，点击授权 API。
在 Step 2 和 Step 3 部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

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