Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

安全软件包

本指南介绍了一系列功能，这些功能会返回有关 Google 账号的其他信任信号。这些信任信号可帮助您的账号管理系统在注册、账号创建期间以及日后针对回访用户做出基于风险的决策。

会话

应用发出的身份验证请求会返回 ID 令牌。例如，当用户按下“使用 Google 账号登录”按钮时，系统会将 ID 令牌返回给显示该按钮的 Android、iOS 或 Web 客户端或服务器应用。

身份验证时刻和用户会话分为以下两种：

用户 <-> Google 会话 ：在用户登录其 Google 账号时建立。Google 管理此会话的生命周期和安全性。auth_time 和 amr 声明可让您深入了解此会话。
用户 <-> 您的应用会话 ：在用户登录您的应用后建立，通常使用“使用 Google 账号登录”发起。您的应用使用这些声明来管理此会话，以改进会话和账号管理决策。

用户通常会在多台设备（例如手机、桌面设备、智能显示屏或电视）上与 Google 服务互动。在每个平台或设备上登录都会建立一个不同的会话。对于 Web 登录，系统会在特定浏览器和 Google 之间建立会话；请注意，无痕浏览模式和隐身模式会创建自己的单独隔离会话。因此，一个 Google 账号可以在各种浏览器和设备上同时拥有多个不同的活跃会话。如需了解详情，请参阅查看具有账号访问权限的设备。

Google 账号状态

Google 账号生命周期的典型事件包括：

用户选择创建 Google 账号，然后
Google 可能会停用该账号，或者用户可能会在按照如何恢复 Google 账号或 Gmail中的步骤操作后重新激活该账号，并且
用户可能会决定删除 Google 账号，或者 Google 可能会因闲置 Google 账号政策而删除该账号。

本指南中所述的安全软件包功能适用于活跃账号或已停用账号，但不适用于 Google 账号创建或删除事件。

Google 可能会随时停用账号，如需了解部分原因，请参阅您的账号已被停用。发生这种情况时，所有活跃的 Google 会话都会终止，并且 Google 的跨账号保护服务会发送 RISC 事件。已停用的账号无法使用“使用 Google 账号登录”功能，这意味着系统永远不会发出 ID 令牌，因此无法使用 ID 令牌来监控已停用的用户账号。

虽然接收跨账号保护 (RISC) 事件是可选的，但这些事件可作为管理用户与应用之间会话的重要信号。如需了解如何实现 RISC 并响应事件，请参阅使用跨账号保护功能保护用户账号。

设置

如需接收其他声明，您的应用需要发布、通过验证并启用安全软件包功能。首先，确认您的应用已发布并已通过验证：

打开 Google Auth Platform
选择或创建应用的工程
点击受众群体 ，并确认 发布状态 为 正式版
点击验证中心 ，并确认 验证状态 为 已验证

接下来，启用其他声明：

点击菜单中的设置
在高级设置 下，选择：
- 会话时长声明 以启用 auth_time
- 身份验证强度声明 以启用 amr

如需了解详情，请访问 OAuth 应用验证帮助中心。

支持的功能

本部分介绍了构成安全软件包的各项功能。

身份验证方法参考

身份验证方法参考 (amr) 是一项 OpenID Connect 声明，用于描述用户与 Google 之间上次身份验证事件期间使用的方法。

在可能的 IANA.AMR 值中，Google 支持以下值，这些值表示：

hwk：使用了硬件安全密钥
mfa：已完成多重身份验证
pwd：使用了密码
swk：使用了软件密钥（例如通行密钥）
sms：使用了短信进行验证
tel：使用了电话进行验证

这些值中的一个或多个会作为字符串的 JSON 数组在 ID 令牌 amr 声明中返回。

仅当有关于所用身份验证方法的信息时，ID 令牌中才会包含 amr 声明，即使请求了该声明，它也可能不存在。

Google 账号所有者可以选择要求使用两步验证，并选择要使用的 MFA 方法。如果 Google 账号启用了高级保护，则需要使用强两步验证方法，例如 Titan 安全密钥 (hwk) 或通行密钥 (swk)。在这两种情况下，如果在登录 Google 账号期间使用了多个因素，则会显示 mfa 值。

mfa 的存在确认了身份验证事件符合 Google 对多重身份验证的要求。例如，使用密码 (pwd) 和通行密钥 (swk) 进行 Google 账号身份验证会导致此声明 "amr": ["mfa", "pwd", "swk"]。

如需详细了解账号安全和用户身份验证：通过高级保护计划获得 Google 最强的账号安全保护、使用通行密钥而非密码登录，以及使用安全密钥进行两步验证。

Workspace 管理员控制受管理的 Workspace 账号的身份验证政策，并且可能要求使用 MFA 或安全密钥。如需了解详情，请参阅 Google 身份管理概览和 Google Cloud 多重身份验证要求登录保护和控制。

身份验证时间

auth_time 声明是 OpenID Connect 协议的标准组成部分，用于提供有关最终用户最近一次向 Google 进行身份验证的时间的信息。它是一个 JSON 数字，表示自 Unix 纪元（1970 年 1 月 1 日 00:00:00 UTC）以来经过的秒数，也是用户上次进行身份验证的时间。您可以将其视为一个时间戳，表示用户上次从当前设备或浏览器登录其 Google 账号的事件。此声明包含在 ID 令牌中，ID 令牌是一个 JSON Web 令牌 (JWT)，其中包含有关身份验证和用户的已验证信息。

auth_time 声明对您的应用很有价值，因为它可以让您确定用户最近一次在他们使用的设备或浏览器上主动登录 Google 账号的时间。这对于安全目的（例如以下情况）尤其重要：

在执行敏感用户操作（例如删除账号、更改账号联系方式或付款）之前，您需要做出明智的决定，以确定您的应用是否应发出额外的升级身份验证质询。Google 不支持 Google 账号重新身份验证请求。
将用户 Google 账号会话的新鲜度和稳定性用作信任信号。一般来说，最近的 auth_time 值表示新鲜度，而较旧的值表示稳定性。

对于 Web 应用，用户登录其 Google 账号后，用户浏览器和操作系统的组合构成一个会话。您的网站也会独立维护一个单独的用户会话。较新的 auth_time 值表示用户最近登录了其 Google 账号。这通常表示用户活跃且参与度高，可以解读为风险较低的信号。

在 Android 等移动平台上，用户通常使用生物识别方法（例如指纹或面部扫描）以及设备专用 PIN 码或图案解锁直接登录其设备。移动应用和平台通常使用这些基于平台的身份验证方法，而不是使用 Google 创建新会话，这会导致 Google 账号登录和相应的 auth_time 更新不频繁。因此，最近的 auth_time 值可能表示长时间运行的 Google 账号会话发生了更改，从而增加了风险。

信任信号是一个细致的主题。预计 auth_time 将与其他信号一起使用，例如是否启用了多重身份验证 (MFA)、使用的身份验证方法以及应用与平台之间的用户会话时长。

请求

用于请求 auth_time 和 amr 声明的具体方法因所使用的 API 而异，但每个 API 都包含一个可选的 claims 参数，用于请求 auth_time 和 amr。

OIDC 协议

直接使用 OAuth 平台时，通过将 auth_time 添加到可选的 claims 请求参数来请求 auth_time。将声明 JSON 对象的 id_token 字段的值设置为 {"auth_time":{"essential":true}}。同样，将 {"amr":{"essential":true}} 添加到 claims 以请求 amr：

https://accounts.google.com/o/oauth2/v2/auth?
response_type=id_token&
client_id=YOUR_CLIENT_ID&
scope=openid email profile&
redirect_uri=https://example.com/user-login&
nonce=123-456-7890&
claims={ "id_token": {
            "auth_time": { "essential":true },
            "amr": {"essential":true}
          }
        }

如需了解详情，请参阅 OpenID Connect。

适用于 Web 的 GIS

适用于 Web 的“使用 Google 账号登录”库有两个 API：HTML 和 JavaScript，用于请求其他声明。例如，使用 JavaScript API 请求 auth_time 和 amr：

<html>
<body>
  <script src="https://accounts.google.com/gsi/client" async></script>
  <script>
    window.onload = function () {
      google.accounts.id.initialize({
        client_id: "YOUR_WEB_CLIENT_ID",
        callback: function(rsp) { console.log(rsp.credential); },
        essential_claims: "auth_time, amr",
      });
      google.accounts.id.renderButton(
        document.getElementById("buttonDiv"),
        { type: "standard", size: "large" }
      );
    }
  </script>
  <div id="buttonDiv"></div>
</body>
</html>

如需了解详情，请参阅适用于 Web 的“使用 Google 账号登录”。

适用于 Android 的 GIS

setClaims 方法和 Claim 对象用于请求 auth_time 和 amr。

更新 build 依赖项，以使用最新版本的 androidx.credentials:credentials-play-services-auth 和 com.google.android.libraries.identity.googleid:googleid 库。

实例化类型为 auth_time 和 amr 的 Claim 对象，并使用 setClaims 将其添加到登录选项列表中：

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
    .setAutoSelectEnabled(true)
    .setFilterByAuthorizedAccounts(true)
    .setServerClientId(WEB_CLIENT_ID)
    .setNonce("NONCE")
    .setClaims(ImmutableList.of(
           new Claim("auth_time", true),
           new Claim("amr", true)
    ))
    .build()

如需了解详情，请参阅使用“使用 Google 账号登录”功能对用户进行身份验证。

iOS

适用于 iOS 的“使用 Google 账号登录”SDK 会向 GIDSignIn 类添加 authTimeClaim 对象和 claims 参数，用于选择性地请求 auth_time 和 amr。

使用 ASWebAuthenticationSession 的应用会更新设备范围内的共享 Cookie jar。GIDSignIn 默认在 iOS 12 或更高版本以及 macOS 10.15 或更高版本中使用此方法。在这种情况下，登录其 Google 账号的用户会通过身份验证，并且会话存储在共享 Cookie jar 中。这里的 auth_time 是用户在设备上进行的上次 Google 身份验证，而不仅仅是在您的应用中。

SFSafariViewController、WKWebView 和 UIWebView 在应用内的隔离沙盒中运行，在使用 auth_time 时请避免使用它们。这里的 auth_time 是用户上次登录应用本身的时间，由于该值始终是最近的时间，因此意义不大。

如需请求 auth_time，请将 GoogleSignIn 依赖项更新到最新版本，并创建 authTimeClaim 对象，然后将其添加到 claims 集。

如需请求 amr，请创建 amrClaim 对象并将其添加到 claims 集。

Swift

将声明集添加到 GIDSignIn.sharedInstance.signIn 方法：

let authTimeClaim = GIDClaim.authTime()
let amrClaim = GIDClaim.amr()
let claims = Set([authTimeClaim, amrClaim])

// Start the sign-in process
GIDSignIn.sharedInstance.signIn(
  withPresenting: rootViewController,
  claims: claims
) { signInResult, error in
  guard let result = signInResult else {
    print("Error signing in: (error?.localizedDescription ?? "No error description")")
    return
  }
  // If sign in succeeded, display the app's main content View
  print("ID Token: (result.user.idToken?.tokenString ?? "No token")")
}

Objective-C

将声明集添加到 signInWithPresentingViewController 方法：

GIDClaim *authTimeClaim = [GIDClaim authTimeClaim];
GIDClaim *AMRClaim = [GIDClaim AMRClaim];
NSSet *claims = [NSSet setWithArray:@[authTimeClaim, AMRClaim]];

// Include the claims set and start the sign-in process
[GIDSignIn.sharedInstance
  signInWithPresentingViewController:self
                                hint:nil
                              claims:claims
                          completion:^(GIDSignInResult * _Nullable signInResult,
                                      NSError * _Nullable error) {
                            // On success signInResult.user.idToken
                            // contains the requested claims.
                          }];

如需了解详情，请参阅将 Google 登录集成到您的 iOS 或 macOS 应用。

响应

如果请求中包含 auth_time 或 amr 声明，则它们会与其他标准声明（例如 iss（颁发者）、sub（主题）、aud（受众群体）和 exp（到期时间））一起在 ID 令牌载荷响应中返回。

缺少声明可能是因为应用未通过验证，或者其他设置已停用（这是默认设置）。按照设置中的说明确认客户端 ID 和正在使用的应用已通过验证，并且已启用其他声明。

auth_time 声明的值是一个 JSON 数字，表示自 Unix 纪元（1970 年 1 月 1 日 00:00:00 UTC）到用户上次进行身份验证的时间之间经过的秒数。

amr 声明的值是一个 JSON 字符串数组，表示上次 Google 账号登录事件期间使用的身份验证方法。

以下是包含 auth_time 和 amr 声明的解码 ID 令牌的示例：

{
  "iss": "https://accounts.google.com",
  "azp": "YOUR_CLIENT_ID",
  "aud": "YOUR_CLIENT_ID",
  "sub": "117726431651943698600",
  "email": "alice@example.com",
  "email_verified": true,
  "nonce": "123-456-7890",
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "nbf": 1748880889,
  "name": "Elisa Beckett",
  "picture": "https://lh3.googleusercontent.com/a/default-user=s96-c",
  "given_name": "Elisa",
  "family_name": "Beckett",
  "iat": 1748881189,
  "exp": 1748884789,
  "jti": "8b5d7ce345787d5dbf14ce6e08a8f88ee8c9b5b1"
}

ID 令牌还包含 iat（发出时间）声明，用于指明 JWT 的发出时间。通过比较 iat 和 auth_time 声明，您可以确定自用户上次进行身份验证以来经过的时间（相对于创建特定 ID 令牌的时间）。例如，如果 iat 为 1748881189，auth_time 为 1748875426，则差值为 5763 秒，表示经过了 1 小时 36 分 3 秒。