令牌类型

本页面介绍了用于向 Google API、Google Cloud 服务和 Google Cloud 上托管的客户创建的服务进行身份验证的令牌类型。

如果您要使用客户端库访问 Google API 和服务,则可以设置应用默认凭据,并且客户端库会为您处理令牌。这是推荐的方法。

什么是令牌

对于身份验证和授权,令牌是一个数字对象,其中包含有关发出请求的主账号的身份以及为其授予的访问权限类型的信息。在大多数身份验证流程中,应用(或应用使用的库)都会将凭据交换为令牌,以确定应用有权访问哪些资源。

令牌类型

不同类型的令牌用于不同的环境。本页面介绍了以下令牌类型:

本页面不讨论 API 密钥客户端 ID,这些被视为凭据。

访问令牌

访问令牌是符合 OAuth 2.0 框架的不透明令牌。这些令牌包含授权信息,但不包含身份信息。它们用于向 Google API 进行身份验证并提供授权信息。

如果您使用应用默认凭据 (ADC)Cloud 客户端库或 Google API 客户端库,则无需管理访问令牌;这些库会自动检索凭据,将其交换为访问令牌,并根据需要刷新访问令牌。

访问令牌内容

访问令牌是不透明的令牌,这意味着它们采用专有格式;应用无法检查访问令牌。

您可以使用 Google OAuth 2.0 tokeninfo 端点从有效(未过期或未撤消)的访问令牌获取信息。

ACCESS_TOKEN 替换为有效、未过期的访问令牌。

curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

此命令会返回类似于以下示例的内容:

{
  "azp": "32553540559.apps.googleusercontent.com",
  "aud": "32553540559.apps.googleusercontent.com",
  "sub": "111260650121245072906",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
  "exp": "1650056632",
  "expires_in": "3488",
  "email": "user@example.com",
  "email_verified": "true"
}

下表列出了需要了解的最重要的字段:

字段 说明
azp 请求令牌的应用的项目、电子邮件地址或服务账号 ID。仅当范围列表中指定了 https://www.googleapis.com/auth/userinfo.email 时才会包含此值。
scope 已添加到此访问令牌的 OAuth 范围。对于 Google Cloud 服务,最佳实践是使用 https://www.googleapis.com/auth/cloud-platform 范围,其中包括所有 Google Cloud API,以及提供精细访问权限控制的 Identity and Access Management (IAM)
expires_in 令牌到期前的秒数。如需了解详情,请参阅访问令牌生命周期

访问令牌生命周期

默认情况下,访问令牌的有效期为 1 小时(3,600 秒)。访问令牌到期后,您的令牌管理代码必须获取新令牌。

如果您需要生命周期更长或更短的访问令牌,可以使用 serviceAccounts.generateAccessToken 方法来创建令牌。此方法允许您选择令牌的生命周期,最长为 12 小时。

如果您想使令牌生命周期延长超出默认值,则必须创建启用 iam.allowServiceAccountCredentialLifetimeExtension 限制条件的组织政策。您无法为用户凭据或外部身份创建生命周期延长的访问令牌。如需了解详情,请参阅创建短期有效的访问令牌

ID 令牌

ID 令牌是符合 OpenID Connect (OIDC) 规范JSON Web 令牌 (JWT)。它们由一组称为“声明”的键值对组成。

与访问令牌(应用无法检查的不透明对象)不同,ID 令牌由应用检查和使用。令牌中的信息(例如令牌的签名者或颁发 ID 令牌的身份)可供应用使用。

如需详细了解 Google 的 OIDC 实现,请参阅 OpenID Connect。 如需了解使用 JWT 的最佳实践,请参阅 JSON Web 令牌当前最佳实践

ID 令牌内容

您可以使用 tokeninfo 端点检查有效的(未过期或未撤消)ID 令牌。

ID_TOKEN 替换为有效、未过期的 ID 令牌。

curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"

此命令会返回类似于以下示例的内容:

{
  "iss": "https://accounts.google.com",
  "azp": "32555350559.apps.googleusercontent.com",
  "aud": "32555350559.apps.googleusercontent.com",
  "sub": "111260650121185072906",
  "hd": "google.com",
  "email": "user@example.com",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

下表介绍了必需或常用的 ID 令牌声明:

声明 说明
iss 令牌的颁发者或签名者。对于 Google 签名的 ID 令牌,此值为 https://accounts.google.com
azp 可选。令牌的接收者。
aud 令牌的受众群体。此声明的值必须与使用令牌对请求进行身份验证的应用或服务匹配。如需了解详情,请参阅 ID 令牌 aud 声明
sub 主体:代表发出请求的主账号的 ID。
iat 令牌颁发时的 Unix 纪元时间
exp 令牌到期时的 Unix 纪元时间

可能存在其他声明,具体取决于颁发者和应用。

ID 令牌 aud 声明

aud 声明描述了创建此令牌时要调用的服务名称。如果服务收到 ID 令牌,则必须验证其完整性(签名)、有效性(是否已过期),以及 aud 声明是否与预期名称匹配。如果不匹配,则服务应拒绝该令牌,因为它可能是用于其他系统的令牌。

通常,获取 ID 令牌时,您使用的是服务账号提供的凭据,而不是用户凭据。这是因为使用用户凭据生成的 ID 令牌的 aud 声明会静态绑定到用户用于进行身份验证的应用。使用服务账号获取 ID 令牌时,您可以为 aud 声明指定不同的值。

ID 令牌生命周期

ID 令牌的有效期最长为 1 小时(3,600 秒)。ID 令牌到期后,您必须获取新令牌。

ID 令牌验证

当您的服务或应用使用 Google 服务(例如 Cloud Run、Cloud Functions 或 Identity-Aware Proxy)时,Google 会为您验证 ID 令牌;在这些情况下,ID 令牌必须由 Google 签名。

如果您需要在应用中验证 ID 令牌,则可以这样做,但这是一个高级工作流。如需了解详情,请参阅验证 ID 令牌

自签名 JSON 网络令牌 (JWT)

您可以使用自签名 JWT 向某些 Google API 进行身份验证,而无需从授权服务器获取访问令牌。

如果您要创建自己的客户端库来访问 Google API,建议您创建自签名 JWT,但这是一种高级工作流。如需详细了解自签名 JWT,请参阅创建自签名 JSON Web 令牌。如需了解使用 JWT 的最佳实践,请参阅 JSON Web 令牌当前最佳实践

刷新令牌

IdP 会管理长期有效的令牌的生命周期。本地 ADC 文件例外,其中包含身份验证库用于为客户端库自动刷新访问令牌的刷新令牌。

联合令牌

联合令牌用作工作负载身份联合执行的中间步骤。联合令牌由 Security Token Service 返回,无法直接使用。它们必须使用服务账号模拟交换为访问令牌

不记名令牌

不记名令牌是通用令牌类别,可向拥有该令牌的一方授予访问权限。访问令牌、ID 令牌和自签名 JWT 都是不记名令牌。

使用不记名令牌进行身份验证依赖于加密协议(例如 HTTPS)提供的安全性;如果不记名令牌被拦截,则可能会被不法分子用来获取访问权限。

如果不记名令牌没有为您的应用场景提供足够的安全性,请考虑增加另一层加密或使用双向传输层安全协议 (mTLS) 解决方案,例如 Chrome Enterprise 进阶版,该解决方案会将对可信设备的访问权限仅授予经过身份验证的用户。

后续步骤