OAuth と Google でログインによるリンクの簡素化

概要

OAuth ベースの Google でログインの簡素化されたリンクは、OAuth リンクの上層に Google でログインを追加します。これにより、Google ユーザーにシームレスなリンクエクスペリエンスを提供し、アカウント作成も可能になります。ユーザーは Google アカウントを使用してサービスに新しいアカウントを作成できます。

OAuth と Google でログインを使用してアカウントリンクを行うには、次の一般的な手順に従います。

まず、ユーザーの Google プロフィールにアクセスすることについてユーザーに同意を求めます。
プロフィールの情報を使用して、ユーザーアカウントが存在するかどうかを確認します。
既存のユーザーの場合は、アカウントをリンクします。
認証システムで Google ユーザーに一致するユーザーが見つからない場合は、Google から受け取った ID トークンを検証します。その後、ID トークンに含まれているプロフィール情報に基づいてユーザーアカウントを作成できます。

この図は、ユーザーが簡素化されたリンクフローを使用して Google アカウントをリンクする手順を示しています。最初のスクリーンショットは、ユーザーがリンクするアプリをどのように選択できるかを示します。2 つ目のスクリーンショットでは、ユーザーがサービスに既存のアカウントがあるかどうかを確認できます。3 番目のスクリーンショットでは、リンクする Google アカウントを選択できます。4 番目のスクリーンショットは、ユーザーの Google アカウントをアプリにリンクするための確認画面を示します。5 番目のスクリーンショットは、Google アプリでユーザーアカウントが正常にリンクされたことを示します。 — 簡素化されたリンクを使用したユーザーのスマートフォンでのアカウントリンク

図 1. ユーザーのスマートフォンでの簡素化されたリンクによるアカウントリンク

簡素化されたリンク: OAuth + 「Google でログイン」フロー

次のシーケンス図は、Streamlined Linking におけるユーザー、Google、トークン交換エンドポイント間のインタラクションの詳細を示しています。

図 2. Streamlined Linking フローのイベントのシーケンス。

役割と責任

次の表に、Streamlined Linking フローにおけるアクターの役割と責任を定義します。

アクター / コンポーネント	GAL ロール	責任
Google アプリ / サーバー	OAuth クライアント	Google でログインのユーザーの同意を取得し、ID アサーション（JWT）をサーバーに渡し、結果のトークンを安全に保存します。
トークン交換エンドポイント	ID プロバイダ / 認可サーバー	ID アサーションを検証し、既存のアカウントを確認し、アカウントリンクインテント（`check`、`get`、`create`）を処理し、リクエストされたインテントに基づいてトークンを発行します。
サービス API	リソースサーバー	有効なアクセストークンが提示された場合にユーザーデータへのアクセスを提供します。

簡素化されたリンクの要件

基本的なウェブ OAuth リンクフローを実装します。サービスは、OAuth 2.0 準拠の認証エンドポイントとトークン交換エンドポイントをサポートする必要があります。
トークン交換エンドポイントは、JSON ウェブトークン（JWT）アサーションをサポートし、check、create、get インテントを実装する必要があります。

Google API クライアント ID を登録します。

OAuth サーバーを実装する

トークン交換エンドポイントは、check、create、get インテントをサポートする必要があります。アカウントのリンクのフローを完了し、さまざまなインテントがいつ使用されるかを確認する手順は次のとおりです。

ユーザーが認証システムにアカウントを持っているかどうか。（ユーザーが [はい] または [いいえ] を選択して決定します）
1. はい : ユーザーは Google アカウントに関連付けられているメールアドレスを使用してプラットフォームにログインしますか？（ユーザーが [はい] または [いいえ] を選択して決定します）
  1. YES : 認証システムに一致するアカウントがユーザーにありますか？（check intent が呼び出されて確認される）
    1. YES : get intent が呼び出され、インテントの取得が成功した場合、アカウントがリンクされます。
    2. いいえ : 新しいアカウントを作成しますか？（ユーザーが [はい] または [いいえ] を選択して決定します）
      1. YES : create intent が呼び出され、作成インテントが正常に返された場合、アカウントがリンクされます。
      2. いいえ : ウェブ OAuth フローがトリガーされ、ユーザーはブラウザにリダイレクトされ、別のメールアドレスでリンクするオプションが表示されます。
  2. いいえ : ウェブ OAuth フローがトリガーされ、ユーザーはブラウザにリダイレクトされ、別のメールアドレスでリンクするオプションが表示されます。
2. NO : 認証システムに一致するアカウントがユーザーにありますか？（check intent が呼び出されて確認される）
  1. YES : get intent が呼び出され、インテントの取得が成功した場合、アカウントがリンクされます。
  2. NO : 作成インテントが正常に返された場合、create intent が呼び出され、アカウントがリンクされます。

既存のユーザーアカウントを確認する（インテントを確認する）

ユーザーが Google プロフィールへのアクセスに同意すると、 Google ユーザーの ID に関する署名付きアサーションを含むリクエスト。「アサーションには、ユーザーの Google アカウント ID、表示されます。アプリケーション用に構成されたトークン交換エンドポイントプロジェクトがリクエストを処理できます

対応する Google アカウントが認証にすでに存在する場合トークン交換エンドポイントは account_found=true を返します。もし Google アカウントが既存のユーザーと一致しません。トークン交換エンドポイントがあります account_found=false で HTTP 404 Not Found エラーを返す。

リクエストは次のようになります。

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

トークン交換エンドポイントでは、以下のパラメータを処理する必要があります。

トークン交換エンドポイントのパラメータ
`intent`	これらのリクエストでは、このパラメータの値は `check`。
`grant_type`	交換されるトークンの種類。これらのリクエストでは、パラメータの値は `urn:ietf:params:oauth:grant-type:jwt-bearer` です。
`assertion`	Google ユーザー ID の署名付きアサーションを提供する JSON Web Token（JWT）。この JWT には、ユーザーの認証情報、 Google アカウント ID、名前、メールアドレス。
`client_id`	Google に割り当てたクライアント ID。
`client_secret`	Google に割り当てたクライアントシークレット。

check インテントリクエストに応答するには、トークン交換エンドポイントで次の手順を行う必要があります。

JWT アサーションを検証してデコードします。
Google アカウントが認証システムにすでに存在するかどうかを確認します。

JWT アサーションを検証してデコードする

JWT アサーションの検証とデコードは、ご使用の言語に対応した JWT デコードライブラリ。使用 Google の公開鍵は、Google Cloud で提供されている JWK または PEM 形式を使用しており、トークンの署名。

デコードされた場合、JWT アサーションは次の例のようになります。

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

トークンの署名を検証するだけでなく、アサーションの発行者（iss フィールド）が https://accounts.google.com の場合、（aud フィールド）は、割り当てられたクライアント ID で、トークンの有効期限が切れていないことを確認します。（exp フィールド）。

email、email_verified、hd フィールドを使用すると、 Google はメールアドレスをホストし、その権威があります。Google がそのユーザーが現在正当なアカウント所有者であることが判明している場合パスワードやその他の本人確認の方法をスキップすることもできます。それ以外の場合、これらのメソッドはを使用して、リンクする前にアカウントを確認できます。

Google が信頼できるケース:

email には @gmail.com という接尾辞が付いています。これは Gmail アカウントです。
email_verified は true で、hd が設定されています。これは G Suite アカウントです。

ユーザーは Gmail や G Suite を使用せずに Google アカウントを登録できます。日時 email に @gmail.com という接尾辞がなく、hd が存在しない場合、Google には含まれません。認証には、信頼できる認証方法、パスワード、その他の本人確認方法を使用することが推奨されます。できます。email_verified も、Google が最初に検証したユーザーに付与できますが、サードパーティの所有権が付与されます。アカウントが変更された可能性があります。

Google アカウントが認証システムに存在するかどうかの確認

次のいずれかの条件を満たしていることを確認します。

アサーションの sub フィールドにある Google アカウント ID がユーザーのものであるデータベースです
アサーションに含まれているメールアドレスが、ユーザーのデータベースに登録されているユーザーと一致している。

いずれかの条件が true の場合、ユーザーは登録済みです。その場合、次のようなレスポンスが返されます。

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

Google アカウント ID もメールアドレスもアサーションがデータベース内のユーザーと一致した場合、ユーザーはまだ登録されていません。インこの場合、トークン交換エンドポイントは HTTP 404 エラーを返す必要があります。 "account_found": "false" を指定します。次に例を示します。

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

自動リンクを処理する（インテントの取得）

対応する Google アカウントが認証にすでに存在する場合トークン交換エンドポイントはユーザーにトークンを返します。もし Google アカウントが既存のユーザーと一致しない（トークン交換エンドポイント） linking_error エラーとオプションの login_hint を返します。

リクエストは次のようになります。

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

トークン交換エンドポイントでは、以下のパラメータを処理する必要があります。

トークン交換エンドポイントのパラメータ
`intent`	これらのリクエストでは、このパラメータの値は `get` になります。
`grant_type`	交換されるトークンの種類。これらのリクエストでは、パラメータの値は `urn:ietf:params:oauth:grant-type:jwt-bearer` です。
`assertion`	Google ユーザー ID の署名付きアサーションを提供する JSON Web Token（JWT）。この JWT には、ユーザーの認証情報、 Google アカウント ID、名前、メールアドレス。
`scope`	省略可: Google がリクエストするように構成したスコープできます。
`client_id`	Google に割り当てたクライアント ID。
`client_secret`	Google に割り当てたクライアントシークレット。

get インテントリクエストに応答するには、トークン交換エンドポイントで次の手順を行う必要があります。

JWT アサーションを検証してデコードします。
Google アカウントが認証システムにすでに存在するかどうかを確認します。

JWT アサーションを検証してデコードする

デコードされた場合、JWT アサーションは次の例のようになります。

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Google が信頼できるケース:

email には @gmail.com という接尾辞が付いています。これは Gmail アカウントです。
email_verified は true で、hd が設定されています。これは G Suite アカウントです。

Google アカウントが認証システムに存在するかどうかの確認

次のいずれかの条件を満たしていることを確認します。

アサーションの sub フィールドにある Google アカウント ID がユーザーのものであるデータベースです
アサーションに含まれているメールアドレスが、ユーザーのデータベースに登録されているユーザーと一致している。

ユーザーのアカウントが見つかった場合、アクセストークンを発行し、次の例のように HTTPS レスポンスの本文で JSON オブジェクトの値を返します。

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": SECONDS_TO_EXPIRATION
}

場合によっては、ユーザーが ID トークンに基づくアカウントのリンクが失敗することがあります。もしトークン交換エンドポイントは、HTTP HTTPS レスポンスで応答する必要があります。 error=linking_error を指定する 401 エラーが返されます。

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Google は、linking_error を含む 401 エラーレスポンスを受信すると、 login_hint をパラメータとして使用して、ユーザーを認可エンドポイントに送信します。「ユーザーがブラウザで OAuth リンクフローを使用してアカウントのリンクを完了します。

使用“使用 Google 账号登录”处理账号创建（创建 intent）

当用户需要在您的服务中创建账号时，Google 会向您的令牌交换端点发出请求，其中指定了 intent=create。

该请求采用以下形式：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

您的令牌交换端点必须能够处理以下参数：

令牌端点参数
`intent`	对于这些请求，此参数的值为 `create`。
`grant_type`	要交换的令牌的类型。对于这些请求，此参数的值为 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	JSON 网络令牌 (JWT)，用于提供 Google 用户身份的签名断言。JWT 包含的信息包括用户的 Google 账号 ID、姓名和电子邮件地址。
`client_id`	您分配给 Google 的客户端 ID。
`client_secret`	您分配给 Google 的客户端密钥。

assertion 参数中的 JWT 包含用户的 Google 账号 ID、姓名和电子邮件地址，您可以使用这些信息在您的服务中创建新账号。

如需响应 create intent 请求，您的令牌交换端点必须执行以下步骤：

验证 JWT 断言并对其进行解码。
验证用户信息并创建新账号。

JWT アサーションを検証してデコードする

デコードされた場合、JWT アサーションは次の例のようになります。

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Google が信頼できるケース:

email には @gmail.com という接尾辞が付いています。これは Gmail アカウントです。
email_verified は true で、hd が設定されています。これは G Suite アカウントです。

验证用户信息并创建新账号

检查是否满足以下任一条件：

断言的 sub 字段中找到的 Google 账号 ID 位于您的用户数据库中。
断言中的电子邮件地址与用户数据库中的用户匹配。

如果满足任一条件，请提示用户将其现有账号与其 Google 账号相关联。为此，请使用 HTTP 401 错误响应请求，该错误指定了 error=linking_error 并将用户的电子邮件地址作为 login_hint。以下是示例响应：

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

当 Google 收到包含 linking_error 的 401 错误响应时，Google 会将用户发送到您的授权端点，并将 login_hint 作为参数。用户在其浏览器中使用 OAuth 关联流程完成账号关联。

如果这两个条件都不满足，请使用 JWT 中提供的信息创建新的用户账号。新账号通常没有设置密码。建议您将“使用 Google 账号登录”添加到其他平台，以便用户可以在应用的所有界面上使用 Google 账号登录。或者，您也可以通过电子邮件向用户发送一个链接，该链接会启动密码恢复流程，让用户设置密码以便在其他平台上登录。

创建完成后，请发出访问令牌，并在 HTTPS 响应正文中的 JSON 对象内返回这些值，如以下示例所示：

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": SECONDS_TO_EXPIRATION
}

Google API クライアント ID を取得する

アカウントリンクの登録プロセスで、Google API クライアント ID を入力する必要があります。OAuth リンクの手順を完了したときに作成したプロジェクトを使用して、API クライアント ID を取得します。手順は次のとおりです。

[クライアント] ページに移動します。
Google APIs プロジェクトを作成または選択します。

プロジェクトにウェブアプリケーションタイプのクライアント ID がない場合は、[クライアントを作成] をクリックして作成します。[承認済みの JavaScript 生成元] ボックスにサイトのドメインが含まれていることを確認してください。ローカルテストや開発を行う場合は、http://localhost と http://localhost:<port_number> の両方を [承認済みの JavaScript 生成元] フィールドに追加する必要があります。

重要なポイント: ローカルテストまたは開発を行う場合は、http://localhost と http://localhost:<port_number> の両方を [承認済みの JavaScript 生成元] フィールドに追加します。
注: クライアント ID は次の例のようになります。
```
1234567890-abc123def456.apps.googleusercontent.com
```

実装を検証する

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 アカウントリンクデモツールを使用して、実装を検証できます。

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

[Google でログイン] ボタンをクリックします。
リンクするアカウントを選択します。
サービス ID を入力します。
必要に応じて、アクセスをリクエストするスコープを 1 つ以上入力します。
[Start Demo] をクリックします。
確認のメッセージが表示されたら、リンクリクエストに同意または拒否できることを確認します。
プラットフォームにリダイレクトされることを確認します。

OAuth と Google でログインによるリンクの簡素化 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

簡素化されたリンク: OAuth + 「Google でログイン」フロー

役割と責任

簡素化されたリンクの要件

OAuth サーバーを実装する

既存のユーザー アカウントを確認する（インテントを確認する）

JWT アサーションを検証してデコードする

Google アカウントが認証システムに存在するかどうかの確認

自動リンクを処理する（インテントの取得）

JWT アサーションを検証してデコードする

Google アカウントが認証システムに存在するかどうかの確認

使用“使用 Google 账号登录”处理账号创建（创建 intent）

JWT アサーションを検証してデコードする

验证用户信息并创建新账号

Google API クライアント ID を取得する

実装を検証する

OAuth と Google でログインによるリンクの簡素化

既存のユーザーアカウントを確認する（インテントを確認する）