OAuth と Google ログインでのリンクを効率化

概要

OAuth ベースの Google ログインを効率化するリンクにより、OAuth リンクの上に Google ログインが追加されます。これにより、Google ユーザーはシームレスなリンクを設定できるようになります。また、アカウントの作成も可能になり、ユーザーは自身の Google アカウントを使用してサービス上で新しいアカウントを作成できるようになります。

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

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

図 1. ユーザーのスマートフォンでのアカウントのリンクの簡素化

リンクを合理化するための要件

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

注: これらのインテントは、基本的なウェブ OAuth リンクフロー用に作成したのと同じトークン交換エンドポイントに実装する必要があります。これらのインテントを処理するために別のエンドポイントを作成しないでください。

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

OAuth サーバーを実装する

トークン交換エンドポイントは、check、create、get インテントをサポートしている必要があります。以下に、アカウント リンクのフローに従って完了した手順と、さまざまなインテントが呼び出されたタイミングを示します。

1. ユーザーの認証システムにアカウントはありますか？（ユーザーが「はい」または「いいえ」を選択したとき）。
   1. はい : ユーザーが Google アカウントに関連付けられているメールアドレスを使用してプラットフォームにログインしていますか？（ユーザーが「はい」または「いいえ」を選択したとき）。
      1. はい : お客様の認証システムに一致するアカウントはありますか？（確認のために check intent が呼び出されます）
         1. YES : get intent が呼び出され、get インテントが正常に返された場合、アカウントはリンクされています。
         2. いいえ : 新しいアカウントを作成しますか？（ユーザーが「はい」または「いいえ」を選択したとき）。
            1. YES: create intent が呼び出され、作成インテントが正常に返された場合、アカウントはリンクされています。
            2. いいえ : ウェブ OAuth フローがトリガーされ、ユーザーはブラウザにリダイレクトされます。別のメールにリンクするオプションがユーザーに表示されます。
      2. いいえ : ウェブの OAuth フローがトリガーされ、ユーザーはブラウザにリダイレクトされます。別のメールにリンクするオプションがユーザーに表示されます。
   2. いいえ : 認証システムに登録されているユーザーと一致するアカウントはありますか？（確認のために check intent が呼び出されます）
      1. YES: get intent が呼び出され、get インテントが正常に返された場合、アカウントはリンクされています。
      2. × : create intent が呼び出され、作成インテントが正常に返された場合、アカウントはリンクされています。

Check for an existing user account (check intent)

After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.

If the corresponding Google account is already present in your authentication system, your token exchange endpoint responds with account_found=true. If the Google account doesn't match an existing user, your token exchange endpoint returns an HTTP 404 Not Found error with account_found=false.

The request has the following form:

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

Your token exchange endpoint must be able to handle the following parameters:

Token endpoint parameters
intent	For these requests, the value of this parameter is check.
grant_type	The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion	A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
client_id	The client ID you assigned to Google.
client_secret	The client secret you assigned to Google.

To respond to the check intent requests, your token exchange endpoint must perform the following steps:

• Validate and decode the JWT assertion.
• Check if the Google account is already present in your authentication system.

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example:

{
  "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": "[e-mail]", // 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
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

• email has a @gmail.com suffix, this is a Gmail account.
• email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verfied can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

• The Google Account ID, found in the assertion's sub field, is in your user database.
• The email address in the assertion matches a user in your user database.

If either condition is true, the user has already signed up. In that case, return a response like the following:

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

{
  "account_found":"true",
}

If neither the Google Account ID nor the email address specified in the assertion matches a user in your database, the user hasn't signed up yet. In this case, your token exchange endpoint needs to reply with a HTTP 404 error that specifies "account_found": "false", as in the following example:

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

{
  "account_found":"false",
}

Handle automatic linking (get intent)

After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.

If the corresponding Google Account is already present in your authentication system, your token exchange endpoint returns a token for the user. If the Google Account doesn't match an existing user, your token exchange endpoint returns a linking_error error and optional login_hint.

The request has the following form:

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

Your token exchange endpoint must be able to handle the following parameters:

Token endpoint parameters
intent	For these requests, the value of this parameter is get.
grant_type	The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion	A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
scope	Optional: Any scopes that you've configured Google to request from users.
client_id	The client ID you assigned to Google.
client_secret	The client secret you assigned to Google.

To respond to the get intent requests, your token exchange endpoint must perform the following steps:

• Validate and decode the JWT assertion.
• Check if the Google account is already present in your authentication system.

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example:

{
  "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": "[e-mail]", // 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
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

• email has a @gmail.com suffix, this is a Gmail account.
• email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verfied can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

• The Google Account ID, found in the assertion's sub field, is in your user database.
• The email address in the assertion matches a user in your user database.

If an account is found for the user, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

In some cases, account linking based on ID token might fail for the user. If it does so for any reason, your token exchange endpoint needs to reply with a HTTP 401 error that specifies error=linking_error, as the following example shows:

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

{
  "error":"linking_error",
  "login_hint":"[e-mail]"
}

When Google receives a 401 error response with linking_error, Google sends the user to your authorization endpoint with login_hint as a parameter. The user completes account linking using the OAuth linking flow in their browser.

通过 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 Web 令牌 (JWT)，用于提供 Google 用户身份的签名断言。JWT 包含用户的 Google 帐号 ID、姓名和电子邮件地址等信息。
client_id	您分配给 Google 的客户端 ID。
client_secret	您分配给 Google 的客户端密钥。

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

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

• 验证并解码 JWT 断言。
• 验证用户信息并创建新帐号。

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example:

{
  "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": "[e-mail]", // 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
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

• email has a @gmail.com suffix, this is a Gmail account.
• email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verfied can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

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

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

• Google 帐号 ID 可在用户的数据库中找到，可在断言的 sub 字段找到。
• 断言中的电子邮件地址与您的用户数据库中的用户匹配。

如果任一条件为 true，请提示用户将其现有帐号与其 Google 帐号相关联。为此，请对请求进行响应，并提供指定 error=linking_error 并将用户的电子邮件地址作为 login_hint 的 HTTP 401 错误。以下是一个示例响应：

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

{
  "error":"linking_error",
  "login_hint":"[e-mail]"
}

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

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

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

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

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

アカウントのリンク登録プロセス中に、Google API クライアント ID を入力する必要があります。

OAuth リンクの手順を実行する際に作成したプロジェクトを使用して、API クライアント ID を取得すること。そのための手順は次のとおりです。

1. Google API Console の [認証情報] ページを開きます。

2. Google API プロジェクトを作成または選択します。

   プロジェクトにウェブ アプリケーション タイプのクライアント ID がない場合は、[認証情報を作成 & OAuth クライアント 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の遊び場のツールを。

ツールで、次の手順を実行します。

1. 設定をクリックし OAuth 2.0の設定]ウィンドウを開きます。
2. OAuthの流れ場では、クライアント側を選択します。
3. OAuthのエンドポイント]フィールドで、[カスタム]を選択します。
4. OAuth2.0エンドポイントとGoogleに割り当てたクライアントIDを対応するフィールドに指定します。
5. ステップ1セクションでは、すべてのGoogleサービスのスコープを選択しないでください。代わりに、このフィールドを空白のままにするか、サーバーに有効なスコープ（または、OAuthスコープを使用しない場合は任意の文字列）を入力してください。設定が完了したら、承認のAPIをクリックします。
6. ステップ2とステップ3のセクションでは、OAuth 2.0のフローを通過し、意図したように各ステップが動作することを確認。

あなたは使用して実装を検証することができ、Googleアカウントのリンクデモツールを。

ツールで、次の手順を実行します。

1. Googleのボタンでサインインしをクリックしてください。
2. リンクするアカウントを選択してください。
3. サービスIDを入力します。
4. オプションで、アクセスを要求する1つ以上のスコープを入力します。
5. スタートデモをクリックしてください。
6. プロンプトが表示されたら、リンク要求に同意して拒否できることを確認します。
7. プラットフォームにリダイレクトされていることを確認します。