此页面由 Cloud Translation API 翻译。

使用 ID 令牌通过后端进行身份验证

一键登录客户端会在用户选择 Google 账号。ID 令牌是已签名的用户身份断言，包含用户的个人资料基本信息，其中可能包含电子邮件地址并且价格经过 Google 验证

当 ID 令牌可用时，您可以使用它们安全地进行应用的后端，或自动为用户注册新账号而无需验证用户的电子邮件地址。

要使用 ID 令牌让用户登录或注册，请将令牌发送到您应用的后端。在后端，使用 Google API 客户端验证令牌或通用的 JWT 库。如果用户尚未登录到您的应用，创建一个新账号。

如果您已选择使用 Nonce 来帮助避免重放攻击，请使用 getNonce 将其与 ID 令牌一起发送到您的后端服务器，预期值。我们强烈建议您考虑使用 Nonce 来提高用户安全性。

从凭据对象中获取 ID 令牌

检索用户的凭据后，请检查凭据对象包含 ID 令牌。如果支持，则将其发送到后端。

Java

public class YourActivity extends AppCompatActivity {

  // ...
  private static final int REQ_ONE_TAP = 2;  // Can be any integer unique to the Activity.
  private boolean showOneTapUI = true;
  // ...

  @Override
  protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
      super.onActivityResult(requestCode, resultCode, data);

      switch (requestCode) {
          case REQ_ONE_TAP:
              try {
                  SignInCredential credential = oneTapClient.getSignInCredentialFromIntent(data);
                  String idToken = credential.getGoogleIdToken();
                  if (idToken !=  null) {
                      // Got an ID token from Google. Use it to authenticate
                      // with your backend.
                      Log.d(TAG, "Got ID token.");
                  }
              } catch (ApiException e) {
                  // ...
              }
              break;
      }
  }
}

Kotlin

class YourActivity : AppCompatActivity() {

    // ...
    private val REQ_ONE_TAP = 2  // Can be any integer unique to the Activity
    private var showOneTapUI = true
    // ...

    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)

        when (requestCode) {
             REQ_ONE_TAP -> {
                try {
                    val credential = oneTapClient.getSignInCredentialFromIntent(data)
                    val idToken = credential.googleIdToken
                    when {
                        idToken != null -> {
                            // Got an ID token from Google. Use it to authenticate
                            // with your backend.
                            Log.d(TAG, "Got ID token.")
                        }
                        else -> {
                            // Shouldn't happen.
                            Log.d(TAG, "No ID token!")
                        }
                    }
                } catch (e: ApiException) {
                    // ...
            }
        }
    }
    // ...
}

验证 ID 令牌的完整性

在通过 HTTPS POST 收到 ID 令牌后，您必须验证完整性令牌的值。

如需验证令牌是否有效，请确保：满足条件：

ID 令牌已由 Google 正确签名。使用 Google 的公钥（适用于 JWK 或 PEM 格式）以验证令牌的签名。这些密钥会定期轮替：检查响应中的 Cache-Control 标头来确定何时您应该再次检索它们。
ID 令牌中 aud 的值等于您应用的某个客户端 ID必须进行此检查，以防止向恶意应用用于访问应用的后端服务器上的同一用户的相关数据。
ID 令牌中 iss 的值等于 accounts.google.com 或 https://accounts.google.com。
ID 令牌的过期时间 (exp) 未过。
如果您需要验证 ID 令牌是否代表 Google Workspace 或 Cloud 组织账号时，您可以查看 hd 声明，该声明表示托管的用户的网域。将资源访问权限限制为只有特定网域。缺少此声明即表示相应账号不属于 Google 托管的域名。

您可以使用 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 可能为 true，因为 Google 最初验证了创建 Google 账号后，该用户会拥有第三方的所有权，后，电子邮件账号可能已更改。

我们强烈建议不要自行编写代码来执行这些验证步骤，建议您使用适用于您平台的 Google API 客户端库， JWT 库。对于开发和调试，您可以调用我们的 tokeninfo 验证端点。

使用 Google API 客户端库

使用某个 Google API 客户端库（例如 Java、 Node.js、 PHP、 Python）是在生产环境中验证 Google ID 令牌的推荐方法。

</ph> <ph type="x-smartling-placeholder">

</ph>

Java

要在 Java 中验证 ID 令牌，请使用 GoogleIdTokenVerifier 对象。例如：

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken.Payload;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;

...

GoogleIdTokenVerifier verifier = new GoogleIdTokenVerifier.Builder(transport, jsonFactory)
    // Specify the CLIENT_ID of the app that accesses the backend:
    .setAudience(Collections.singletonList(CLIENT_ID))
    // Or, if multiple clients access the backend:
    //.setAudience(Arrays.asList(CLIENT_ID_1, CLIENT_ID_2, CLIENT_ID_3))
    .build();

// (Receive idTokenString by HTTPS POST)

GoogleIdToken idToken = verifier.verify(idTokenString);
if (idToken != null) {
  Payload payload = idToken.getPayload();

  // Print user identifier
  String userId = payload.getSubject();
  System.out.println("User ID: " + userId);

  // Get profile information from payload
  String email = payload.getEmail();
  boolean emailVerified = Boolean.valueOf(payload.getEmailVerified());
  String name = (String) payload.get("name");
  String pictureUrl = (String) payload.get("picture");
  String locale = (String) payload.get("locale");
  String familyName = (String) payload.get("family_name");
  String givenName = (String) payload.get("given_name");

  // Use or store profile information
  // ...

} else {
  System.out.println("Invalid ID token.");
}

GoogleIdTokenVerifier.verify() 方法验证 JWT 签名、aud 声明、iss 声明以及 exp 项版权主张。

如果您需要验证 ID 令牌是否代表 Google Workspace 或 Cloud 组织账号，您可以通过检查域名来验证 hd 所有权声明由 Payload.getHostedDomain() 方法返回。该 email 声明不足以保证账号是由网域管理或组织。

。 <ph type="x-smartling-placeholder">

</ph>

Node.js

要在 Node.js 中验证 ID 令牌，请使用适用于 Node.js 的 Google Auth 库。安装该库：

npm install google-auth-library --save

然后，调用 verifyIdToken() 函数。例如：

const {OAuth2Client} = require('google-auth-library');
const client = new OAuth2Client();
async function verify() {
  const ticket = await client.verifyIdToken({
      idToken: token,
      audience: CLIENT_ID,  // Specify the CLIENT_ID of the app that accesses the backend
      // Or, if multiple clients access the backend:
      //[CLIENT_ID_1, CLIENT_ID_2, CLIENT_ID_3]
  });
  const payload = ticket.getPayload();
  const userid = payload['sub'];
  // If the request specified a Google Workspace domain:
  // const domain = payload['hd'];
}
verify().catch(console.error);

verifyIdToken 函数用于验证 JWT 签名、aud 声明、exp 声明以及 iss 声明。

如果您需要验证 ID 令牌是否代表 Google Workspace 或 Cloud 组织账号时，您可以查看 hd 声明，该声明表示托管的用户的网域。将资源访问权限限制为仅允许成员访问时，必须使用此设置特定网域的用户缺少此声明即表示该账号不属于 Google 托管的域。

。 <ph type="x-smartling-placeholder">

</ph>

PHP

要在 PHP 中验证 ID 令牌，请使用适用于 PHP 的 Google API 客户端库。安装该库（例如，使用 Composer）：

composer require google/apiclient

然后，调用 verifyIdToken() 函数。例如：

require_once 'vendor/autoload.php';

// Get $id_token via HTTPS POST.

$client = new Google_Client(['client_id' => $CLIENT_ID]);  // Specify the CLIENT_ID of the app that accesses the backend
$payload = $client->verifyIdToken($id_token);
if ($payload) {
  $userid = $payload['sub'];
  // If the request specified a Google Workspace domain
  //$domain = $payload['hd'];
} else {
  // Invalid ID token
}

verifyIdToken 函数用于验证 JWT 签名、aud 声明、exp 声明以及 iss 声明。

。 <ph type="x-smartling-placeholder">

</ph>

Python

要在 Python 中验证 ID 令牌，请使用 verify_oauth2_token 函数。例如：

from google.oauth2 import id_token
from google.auth.transport import requests

# (Receive token by HTTPS POST)
# ...

try:
    # Specify the CLIENT_ID of the app that accesses the backend:
    idinfo = id_token.verify_oauth2_token(token, requests.Request(), CLIENT_ID)

    # Or, if multiple clients access the backend server:
    # idinfo = id_token.verify_oauth2_token(token, requests.Request())
    # if idinfo['aud'] not in [CLIENT_ID_1, CLIENT_ID_2, CLIENT_ID_3]:
    #     raise ValueError('Could not verify audience.')

    # If the request specified a Google Workspace domain
    # if idinfo['hd'] != DOMAIN_NAME:
    #     raise ValueError('Wrong domain name.')

    # ID token is valid. Get the user's Google Account ID from the decoded token.
    userid = idinfo['sub']
except ValueError:
    # Invalid token
    pass

verify_oauth2_token 函数验证 JWT 签名、aud 声明和 exp 声明。您还必须验证 hd 检查 verify_oauth2_token 返回。如果多个客户端访问后端服务器，另请手动验证 aud 声明。

调用 tokeninfo 端点

为调试验证 ID 令牌签名的一种简单方法是使用 tokeninfo 端点。调用此端点涉及这个额外的网络请求会为您完成大部分的验证工作，验证和载荷提取。不适合在生产环境中使用因为请求可能会受到限制或出现间歇性错误。

如需使用 tokeninfo 端点验证 ID 令牌，请创建 HTTPS POST 或 GET 请求发送到端点，并在 id_token 参数。例如，要验证令牌“XYZ123”，请发出以下 GET 请求：

https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123

如果令牌经过正确签名，并且 iss 和 exp 具有预期值，就会收到 HTTP 200 响应，其中正文包含 JSON 格式的 ID 令牌声明。以下是示例响应：

{
 // These six fields are included in all Google ID Tokens.
 "iss": "https://accounts.google.com",
 "sub": "110169484474386276334",
 "azp": "1008719970978-hb24n2dstb40o45d4feuo2ukqmcc6381.apps.googleusercontent.com",
 "aud": "1008719970978-hb24n2dstb40o45d4feuo2ukqmcc6381.apps.googleusercontent.com",
 "iat": "1433978353",
 "exp": "1433981953",

 // These seven fields are only included when the user has granted the "profile" and
 // "email" OAuth scopes to the application.
 "email": "testuser@gmail.com",
 "email_verified": "true",
 "name" : "Test User",
 "picture": "https://lh4.googleusercontent.com/-kYgzyAWpZzJ/ABCDEFGHI/AAAJKLMNOP/tIXL9Ir44LE/s99-c/photo.jpg",
 "given_name": "Test",
 "family_name": "User",
 "locale": "en"
}

警告：收到这些版权主张后，你仍然需要检查 aud 声明是否包含应用的某个客户端 ID。如果有，则令牌对客户端有效并且专门用于您的客户端，您可以安全地检索和使用用户在 sub 声明中的唯一 Google ID。

如果您需要验证 ID 令牌是否代表 Google Workspace 账号，可以先查看 hd 声明，指示用户的托管网域。只有在以下情况下，从而仅允许特定网域中的成员访问资源。缺少此声明表示该账号不属于 Google Workspace 托管网域。

创建账号或会话

验证令牌后，检查用户是否在您的用户中数据库。如果是这样，请为用户建立经过身份验证的会话。如果用户，则请使用下面的信息创建新的用户记录 ID 令牌载荷中，并为用户建立会话。您可以提示当您检测到某个事件时，新用户。

保护用户的启用了跨账号保护功能的账号

当您依靠 Google 来登录某个用户时，您将自动享受到 Google 为保护用户数据而构建的安全功能和基础架构。不过，在极少数情况下，万一用户的 Google 账号遭到盗用，或者存在其他重大安全性事件，那么您的应用也可能容易受到攻击。为了更好地保护您的使用跨账号保护以接收来自 Google 的安全提醒。收到这些事件后了解有关用户 Google 账号安全性的重要变化，并然后，您可以对该服务采取措施，以确保您账号的安全。