本页面介绍了 Google 作为 OpenID Connect 提供商的实现，并提供了 Google OIDC 端点的技术参考。OpenID Connect (OIDC) Core 1.0 规范定义了用于对用户进行身份验证和获取身份信息的协议。
此参考文档并非旨在提供有关如何实现 OIDC 的分步说明；如需了解实现详情，请参阅 OpenID Connect 指南。
发现文档
发现文档包含有关 Google 的 OpenID Connect 配置的元数据，如 OpenID Connect Discovery 1.0 规范中所定义。
网址： https://accounts.google.com/.well-known/openid-configuration
支持的请求方法： GET
响应正文
响应字段以 JSON 对象的形式返回，位于 HTTP 响应的正文中，以响应请求者向 https://accounts.google.com/.well-known/openid-configuration 发出的 GET 请求。
| 字段 | 类型 | 说明 |
|---|---|---|
issuer |
string |
发卡机构标识符。使用 https 方案的区分大小写的网址。现代值为 https://accounts.google.com；不过，对于旧版实现，也会返回 accounts.google.com。 |
authorization_endpoint |
string |
授权端点的网址。 |
device_authorization_endpoint |
string |
设备授权端点的网址。 |
token_endpoint |
string |
令牌端点的网址。 |
userinfo_endpoint |
string |
UserInfo 端点的网址。 |
revocation_endpoint |
string |
撤消端点的网址。 |
jwks_uri |
string |
JSON Web 密钥集 (JWKS) 文档的网址。 |
response_types_supported |
array |
支持的 response_type 值列表。 |
response_modes_supported |
array |
支持的 response_mode 值列表。 |
authorization_response_iss_parameter_supported |
boolean |
一个布尔值，用于指示是否支持 RFC 9207。 |
subject_types_supported |
array |
支持的正文标识符类型列表。 |
id_token_signing_alg_values_supported |
array |
用于签署 ID 令牌的支持算法的列表。 |
scopes_supported |
array |
支持的范围值列表。 |
claims_supported |
array |
支持的声明列表。 |
token_endpoint_auth_methods_supported |
array |
令牌端点支持的身份验证方法列表。 |
code_challenge_methods_supported |
array |
支持的 PKCE 代码质询方法列表。 |
grant_types_supported |
array |
受支持的 OAuth 2.0 授权类型列表。 |
ID 令牌（声明）
响应中返回的 id_token 值是一个已签名的 JSON Web 令牌 (JWT)，必须使用从发现文档中的 jwks_uri 获取的密钥材料进行验证。下表介绍了已解码的 ID 令牌载荷的内容。
| 声明 | 类型 | 说明 |
|---|---|---|
iss |
string |
必需。响应发行机构的发行机构标识符。通常为 https://accounts.google.com；不过，对于旧版实现，也会返回 accounts.google.com。 |
sub |
string |
必需。用户的标识符，在所有 Google 账号中必须具有唯一性，并且不得重复使用。Google 账号在不同的时间点可以有多个电子邮件地址，但 sub 值始终保持不变。在应用中使用 sub 作为用户的唯一标识符键。长度上限为 255 个区分大小写的 ASCII 字符。 |
azp |
string |
授权演示者的客户端标识符，从 Google Cloud 控制台获取。只有当 ID 令牌的请求方与 ID 令牌的受众群体不同时，才需要此声明。 |
aud |
string |
必需。ID 令牌的目标受众群体。这是您的应用的客户端标识符，可从 Google Cloud 控制台获取。 |
iat |
integer |
必需。ID 令牌的颁发时间。以 Unix 纪元时间（整数秒数）表示。 |
exp |
integer |
必需。ID 令牌不得被接受的过期时间（含）。以 Unix 纪元时间（整数秒数）表示。 |
nonce |
string |
您的应用在身份验证请求中提供的 nonce 的值。您应确保该值只出现一次，以防范重放攻击。 |
auth_time |
integer |
用户身份验证发生的时间，以 JSON 数字表示自 Unix 纪元（1970 年 1 月 1 日 00:00:00 UTC）以来经过的秒数。当身份验证请求 claims 参数中包含 auth_time 声明时提供。 |
at_hash |
string |
访问令牌哈希。提供验证，确保访问令牌与身份令牌相关联。如果 ID 令牌是在服务器流程中发放的，且包含 access_token 值，则始终会包含此声明。 |
email |
string |
用户的电子邮件地址。仅当您在请求中包含 email 范围时，系统才会提供此字段。此声明的值可能并非此账号独有，并且可能会随时间而变化，因此您不应使用此值作为与用户记录相关联的主标识符。您也不能依赖 email 声明的网域来识别 Google Workspace 或 Cloud 组织的成员；请改用 hd 声明。警告：请勿使用电子邮件地址作为标识符，因为一个 Google 账号在不同时间点可以有多个电子邮件地址。始终使用 sub 字段作为用户的标识符。 |
email_verified |
boolean |
如果用户的电子邮件地址已通过验证，则为 True；否则为 false。 |
name |
string |
用户的全名（采用可显示的形式）。当请求范围包含字符串 profile 或 ID 令牌是从令牌刷新返回时，可能会提供此参数。 |
picture |
string |
用户个人资料照片的网址。如果请求范围包含字符串 profile，或者 ID 令牌是从令牌刷新返回的，则可能会提供此参数。 |
given_name |
string |
用户的名字。如果存在 name 声明，则可能会提供。 |
family_name |
string |
用户的姓氏。如果存在 name 声明，则可能会提供。 |
hd |
string |
与用户的 Google Workspace 或 Cloud 组织相关联的网域。仅当用户属于 Google Cloud 组织时提供。当您将对资源的访问权限限制为仅限特定网域的成员时，必须检查此声明。如果缺少此声明，则表示相应账号不属于 Google 托管域名。 |
授权端点
授权端点用于对用户进行身份验证并获取授权代码或令牌。
网址： https://accounts.google.com/o/oauth2/v2/auth
支持的请求方法： GET、POST
请求参数
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
client_id |
string |
必需 | 从 Google Cloud 控制台获取的客户端标识符字符串。 |
nonce |
string |
可选 | 由您的应用生成的随机值，用于启用重放保护。仅当请求 ID 令牌时（即当 response_type 包含 id_token 时）才需要此参数。 |
response_type |
string |
必需 | 确定要使用的流程。如果值为 code，则启动授权代码流程，需要向令牌端点提供 POST 才能获取令牌。如果值为 token、id_token、token id_token 或 id_token token，则启动隐式流，需要在重定向 URI 中使用 JavaScript 从 URI 片段检索令牌。强烈建议不要以任何形式使用 token，因为这会在网址中泄露访问令牌；OAuth 2.1 中禁止使用此值。 |
response_mode |
string |
可选 | 指定授权响应的传送方式。如果 response_type 为 code，则默认值为 query。对于其他响应类型，默认值为 fragment。支持的值：query、fragment、form_post。 |
redirect_uri |
string |
必需 | 确定响应的发送位置。此参数的值必须与您在 Google Cloud 控制台中设置的某个授权重定向值完全一致（包括 HTTP 或 HTTPS 架构、大小写和末尾的“/”，如果有）。重定向 URI 和已获授权的 JavaScript 来源必须遵循 OAuth 2.0 URI 验证文档中概述的验证规则。 |
scope |
string |
必需 | 以空格分隔的无序范围列表。该列表必须包含 openid 值，然后包含 profile 值、email 值或同时包含这两个值。您还可以包含非 OIDC 范围。如果存在 profile 范围值，ID 令牌可能会（但不保证）包含用户的默认 profile 声明。如果存在 email 范围值，则 ID 令牌包含 email 和 email_verified 声明。如需了解详情，请参阅 OAuth 2.0 范围。 |
state |
string |
推荐 | 一种在协议中往返的不透明字符串；也就是说，在授权代码流程中，它作为 URI 参数返回，而在隐式流程中，它作为 URI 片段返回。state 可用于关联请求和响应。由于您的 redirect_uri 可能会被猜到，因此使用 state 值可以提高您对传入连接是由应用发起的身份验证请求的结果的信心。这可以防范跨站请求伪造等攻击。 |
access_type |
string |
可选 | 允许的值包括 offline 和 online。如果您的应用需要在用户不在浏览器前时刷新访问令牌，请使用 offline。此值是获取返回的刷新令牌所必需的值。 |
hd |
string |
可选 | 简化 Google Cloud 组织所拥有账号的登录流程。通过添加 Google Cloud 组织网域（例如 mycollege.edu），您可以指明应针对该网域中的账号优化账号选择界面。如需针对 Google Cloud 组织账号（而非仅针对一个 Google Cloud 组织网域）进行优化，请将值设置为星号 (*)：hd=*。 |
login_hint |
string |
可选 | 当应用知道它要对哪个用户进行身份验证时，它可以将此参数作为提示提供给身份验证服务器。传递此提示会抑制账号选择器，并预先填充登录表单上的电子邮件框或选择适当的会话，这有助于您避免因应用登录错误的用户账号而导致的问题。该值可以是电子邮件地址，也可以是 sub 字符串（相当于用户的 Google ID）。 |
prompt |
string |
可选 | 一个以空格分隔的字符串值列表，用于指定授权服务器是否提示用户重新进行身份验证和同意。可能的值：none（无界面）、consent（提示征求同意）、select_account（提示选择账号）。 |
hl |
string |
可选 | 用于指定登录界面、账号选择器界面和意见征求界面的显示语言的 BCP 47 语言标记。不建议使用此参数，因为浏览器设置和 Google 账号偏好设置通常更能反映用户的语言偏好。 |
include_granted_scopes |
boolean |
可选 | 如果此参数的值为 true，并且授权请求获得批准，则授权将包含之前授予此用户/应用组合的其他范围的任何授权；请参阅增量授权。 |
claims |
object |
可选 | claims 参数用于指定要在 UserInfo 响应或 ID 令牌中包含的一个或多个可选字段。如需请求 auth_time 声明，请使用 claims={\"id_token\":{\"auth_time\":{\"essential\":true}}}。 |
响应参数
授权响应通过 HTTP GET 重定向传递到客户端的重定向 URI (redirect_uri)。响应参数会附加到重定向 URI 的查询字符串或网址片段中，具体取决于 response_type 和 response_mode。
| 参数 | 类型 | 说明 |
|---|---|---|
iss |
string |
发卡机构标识符。根据 RFC 9207，系统始终会返回此参数，并将其设置为 https://accounts.google.com。 |
code |
string |
可用于交换访问令牌和 ID 令牌的授权代码。 |
state |
string |
与请求中的 state 参数相同的值。 |
id_token |
string |
包含用户身份信息的 JSON Web 令牌 (JWT)。 |
access_token |
string |
可发送到 Google API 的访问令牌。 |
token_type |
string |
返回的令牌类型。始终为 Bearer。 |
expires_in |
integer |
访问令牌的生命周期（以秒为单位），相对于令牌的签发时间。 |
scope |
string |
由 code 或 access_token 授予的访问权限范围，以空格分隔的区分大小写的字符串列表表示。 |
error |
string |
如果请求失败，则为错误代码。 |
error_description |
string |
请求失败时的错误说明。 |
错误响应
对于授权端点，错误会以查询字符串或网址片段中的参数形式返回给客户端的 redirect_uri，或者以 Google 托管的错误页面的形式向用户显示。
重定向的错误
系统可能会向您的 redirect_uri 返回以下错误代码：
| 错误 | 说明 |
|---|---|
access_denied |
用户或授权服务器拒绝了请求。 |
invalid_request |
请求缺少必需的参数、包含无效的参数值、多次包含同一参数，或者格式有误。 |
unauthorized_client |
客户端无权使用此方法请求授权代码。 |
unsupported_response_type |
授权服务器不支持使用此方法获取授权代码。 |
invalid_scope |
所请求的范围无效、未知或格式错误。 |
面向用户的错误
在某些情况下（例如当 client_id 或 redirect_uri 无效时），授权服务器无法安全地将用户重定向回您的应用。在这些情况下，系统会直接向用户显示错误页面。
| 错误 | 说明 |
|---|---|
admin_policy_enforced |
由于 Google Workspace 管理员的政策，相应 Google 账号无法授权一个或多个请求的范围。如需详细了解管理员如何限制访问权限，直到明确向 OAuth 客户端标识符授予访问权限为止，请参阅 Google Workspace 管理员帮助文章。 |
disallowed_useragent |
授权端点显示在 Google 的 OAuth 2.0 政策禁止使用的嵌入式用户代理中。 |
org_internal |
请求中的 OAuth 客户端标识符属于一个项目，该项目限制对特定 Google Cloud 组织中的 Google 账号的访问权限。 |
deleted_client |
用于发出请求的 OAuth 客户端已被删除。对于未使用的客户端，可以手动或自动删除。 |
invalid_grant |
使用 PKCE 时，code_challenge 参数无效或缺失。刷新访问令牌或使用增量授权时，令牌可能已过期、失效，或者用户账号可能已被删除或停用。 |
redirect_uri_mismatch |
请求中传递的 redirect_uri 与客户端标识符的授权重定向 URI 不匹配。在 Google Cloud 控制台中查看已获授权的重定向 URI。如果请求使用已弃用的 OAuth 带外 (OOB) 流程，也可能会出现此错误。 |
invalid_client |
发出请求的来源未获得相应客户端的授权，客户端配置不正确，或者 OAuth 客户端密钥不正确。 |
origin_mismatch |
发起授权请求的 JavaScript 的方案、网域和/或端口与为 OAuth 客户端标识符注册的已获授权的 JavaScript 来源 URI 不匹配。在 Google Cloud 控制台中查看已获授权的 JavaScript 来源。 |
invalid_request |
请求存在问题。这可能是因为请求格式有误、缺少必需参数或使用了 Google 不支持的授权方法。 |
令牌端点
令牌端点用于将授权代码交换为访问令牌和 ID 令牌。
网址： https://oauth2.googleapis.com/token
支持的请求方法： POST
请求参数（授权代码授予）
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
code |
string |
必需 | 从授权端点收到的授权代码。 |
client_id |
string |
必需 | 从 Google Cloud 控制台获取的应用的客户端标识符。 |
client_secret |
string |
必需 | 从 Google Cloud 控制台获取的应用的客户端密钥。 |
redirect_uri |
string |
必需 | 初始授权请求中使用的重定向 URI。重定向 URI 和已获授权的 JavaScript 来源必须遵循 OAuth 2.0 URI 验证文档中概述的验证规则。 |
grant_type |
string |
必需 | 必须设置为authorization_code。 |
请求参数（设备流程）
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
client_id |
string |
必需 | 从 Google Cloud 控制台获取的应用的客户端标识符。 |
client_secret |
string |
必需 | 从 Google Cloud 控制台获取的应用的客户端密钥。 |
device_code |
string |
必需 | 设备授权端点返回的 device_code。 |
grant_type |
string |
必需 | 必须设置为urn:ietf:params:oauth:grant-type:device_code。 |
请求参数（刷新访问令牌）
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
client_id |
string |
必需 | 从 Google Cloud 控制台获取的应用的客户端标识符。 |
client_secret |
string |
必需 | 从 Google Cloud 控制台获取的应用的客户端密钥。 |
grant_type |
string |
必需 | 必须设置为 OpenID Connect 刷新令牌规范中定义的 refresh_token。 |
refresh_token |
string |
必需 | 通过授权代码交换返回的刷新令牌。 |
scope |
string |
可选 | 以空格分隔的范围列表，其中包含为新访问令牌请求的范围。所请求的范围必须是原始授权请求中授予的范围的子集。 |
响应正文
响应字段以 JSON 对象的形式返回，位于 HTTP 响应的正文中，以响应请求者向 https://oauth2.googleapis.com/token 发出的 POST 请求。
| 字段 | 类型 | 说明 |
|---|---|---|
access_token |
string |
可发送到 Google API 的访问令牌。 |
expires_in |
integer |
访问令牌的生命周期（以秒为单位），相对于令牌的签发时间。 |
id_token |
string |
包含用户身份信息的 JSON Web 令牌 (JWT)。此令牌在初始授权码交换期间返回，如果授予了 openid 范围，则还可以在刷新令牌请求期间返回。 |
scope |
string |
由 access_token 授予的访问权限的范围，表示为以空格分隔且区分大小写的字符串列表。 |
token_type |
string |
返回的令牌类型。始终为 Bearer。 |
refresh_token |
string |
（可选）可用于获取新访问令牌的令牌。只有在请求了 access_type=offline 的情况下，系统才会在此字段中返回授权代码的初始交换。 |
refresh_token_expires_in |
integer |
（可选）刷新令牌的剩余生命周期（以秒为单位）。仅当用户授予基于时间的访问权限时，才会设置此值。 |
错误响应
如果请求失败，授权服务器会返回一个包含以下字段的 JSON 对象：
| 字段 | 类型 | 说明 |
|---|---|---|
error |
string |
错误代码。 |
error_description |
string |
请求失败时的错误说明。 |
下表介绍了可能的错误代码及其关联的 HTTP 状态代码：
| 错误 | HTTP 状态代码 | 说明 |
|---|---|---|
invalid_request |
400 |
请求缺少必需参数、包含无效的参数值，或者格式不正确。 |
invalid_client |
401 |
客户端身份验证失败。例如，client_id 或 client_secret 无效，或者客户端类型不正确。 |
invalid_grant |
400 |
提供的授权代码、刷新令牌或设备代码无效、已过期、已被撤消，或者与授权请求中使用的重定向 URI 不匹配。 |
unauthorized_client |
400 |
经过身份验证的客户端无权使用此授权许可类型。 |
unsupported_grant_type |
400 |
授权服务器不支持授权许可类型。 |
invalid_scope |
400 |
所请求的范围无效、未知或格式错误。 |
authorization_pending |
428 |
（设备流程）用户尚未完成授权流程。 |
slow_down |
429 |
（设备流程）设备发送轮询请求的频率过高。 |
access_denied |
403 |
（设备流程）用户拒绝授予设备访问权限。 |
expired_token |
400 |
（设备流程）device_code已过期。 |
admin_policy_enforced |
400 |
由于 Google Workspace 管理员强制执行的政策，用户无法授权所请求的范围。 |
org_internal |
403 |
客户端标识符是项目的一部分，该项目限制对特定 Google Cloud 组织的访问权限。 |
设备授权端点
设备授权端点用于 OAuth 2.0 设备流程，以获取用户代码和验证网址，供输入能力有限的设备使用。
网址： https://oauth2.googleapis.com/device/code
支持的请求方法： POST
请求参数
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
client_id |
string |
必需 | 从 Google Cloud 控制台获取的应用的客户端标识符。 |
scope |
string |
必需 | 以空格分隔的范围列表，用于标识应用可以代表用户访问的资源。 |
响应正文
响应是包含以下字段的 JSON 对象：
| 字段 | 类型 | 说明 |
|---|---|---|
device_code |
string |
Google 唯一分配的值，用于标识运行请求授权的应用的设备。 |
user_code |
string |
一个区分大小写的值，用于向 Google 标识应用请求访问的范围。您的用户界面会指示用户在输入功能更丰富的其他设备上输入此值。 |
verification_url |
string |
用户必须在单独的设备上访问的网址，以便输入 user_code 并授予或拒绝您的应用访问权限。 |
expires_in |
integer |
device_code 和 user_code 的有效时长（以秒为单位）。 |
interval |
integer |
设备在轮询请求之间应等待的时长（以秒为单位）。 |
撤消端点
通过撤消端点，您的应用可以撤消访问令牌或刷新令牌。
网址： https://oauth2.googleapis.com/revoke
支持的请求方法： POST
请求参数
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
token |
string |
必需 | 您要撤消的访问令牌或刷新令牌。 |
响应正文
如果撤消成功，则响应为空的 HTTP 200 OK。如果撤消失败，则会以 JSON 对象的形式返回错误响应。
| 字段 | 类型 | 说明 |
|---|---|---|
error |
string |
如果请求失败，则为错误代码。 |
error_description |
string |
请求失败时的错误说明。 |
下表介绍了可能的错误代码：
| 错误 | 说明 |
|---|---|
invalid_token |
请求中提供的令牌已过期或已被撤消。 |
invalid_request |
请求缺少必需参数、包含无效的参数值，或者格式不正确。 |
UserInfo 端点
UserInfo 端点会返回经过身份验证的用户的个人资料信息。
网址： https://openidconnect.googleapis.com/v1/userinfo
支持的请求方法： GET、POST
请求标头
| 标题 | 说明 |
|---|---|
Authorization |
必需。必须设置为 Bearer: access_token。 |
响应正文
响应字段以 JSON 对象的形式返回，位于 HTTP 响应的正文中，以响应请求者的 GET 或 POST 请求 (https://openidconnect.googleapis.com/v1/userinfo)。
| 字段 | 类型 | 说明 |
|---|---|---|
sub |
string |
必需。用户的标识符，在所有 Google 账号中必须具有唯一性，并且不得重复使用。区分大小写且不超过 255 个字符的字符串。 |
name |
string |
用户的全名（采用可显示的形式）。 |
given_name |
string |
用户的名字。 |
family_name |
string |
用户的姓氏。 |
picture |
string |
用户个人资料照片的网址。 |
email |
string |
用户的电子邮件地址。 |
email_verified |
boolean |
用户的电子邮件地址是否已通过验证。 |
hd |
string |
与用户的 Google Workspace 或 Cloud 组织关联的托管网域。 |
Tokeninfo 端点
tokeninfo 端点是一种 Google 特定的实现，用于验证 ID 令牌以进行调试。
网址： https://oauth2.googleapis.com/tokeninfo
支持的请求方法： GET、POST
请求参数
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
id_token |
string |
必需 | 要验证的 ID 令牌。 |
响应正文
响应字段以 JSON 对象的形式返回，位于 HTTP 响应的正文中，以响应请求者的 GET 或 POST 请求 (https://oauth2.googleapis.com/tokeninfo)。
| 字段 | 类型 | 说明 |
|---|---|---|
iss |
string |
发卡机构标识符。始终为 https://accounts.google.com。 |
sub |
string |
用户的标识符，在所有 Google 账号中必须具有唯一性，并且不得重复使用。 |
aud |
string |
ID 令牌的目标受众群体。这是您的应用的客户端标识符，可从 Google Cloud 控制台获取。 |
iat |
integer |
JWT 的签发时间。以自 1970-01-01T0:0:0Z 起的秒数表示（以世界协调时间 [UTC] 为准）。 |
exp |
integer |
ID 令牌的过期时间，在此时间之后，不得接受该令牌进行处理。以自 1970-01-01T0:0:0Z 起的秒数表示（以世界协调时间 [UTC] 为准）。 |
email |
string |
用户的电子邮件地址。 |
email_verified |
string |
用户的电子邮件地址是否已通过验证。值是字符串 "true" 或 "false"。 |
access_type |
string |
原始授权请求中请求的访问权限类型。 |
azp |
string |
授权演示者的客户端标识符，从 Google Cloud 控制台获取。 |
scope |
string |
授予令牌的以空格分隔的范围列表。 |
alg |
string |
用于对 ID 令牌进行签名的算法。 |
kid |
string |
用于对 ID 令牌进行签名的密钥 ID。 |
typ |
string |
令牌的类型。始终为 JWT。 |