OpenID Connect

Google 的 OAuth 2.0 API 既可用于身份验证,也可用于授权。本文档介绍了用于身份验证的 OAuth 2.0 实现,它符合 OpenID Connect 规范,并经过 OpenID 认证使用 OAuth 2.0 访问 Google API 中的文档也适用于此服务。如果您想以交互方式探索此协议,建议您使用 Google OAuth 2.0 Playground。如需获得有关 Stack Overflow 的帮助,请使用 'google-oauth' 标记您的问题。

设置 OAuth 2.0

您必须先在 Google API Console 中设置项目以获取 OAuth 2.0 凭据,设置重定向 URI,并视需要自定义用户同意屏幕上显示的品牌信息,然后您的应用才可以使用 Google OAuth 2.0 身份验证系统进行应用登录。您还可以使用 API Console 创建服务帐号、启用结算功能、设置过滤,以及执行其他任务。如需了解详情,请参阅 Google API Console帮助

获取 OAuth 2.0 凭据

您需要使用 OAuth 2.0 凭据(包括客户端 ID 和客户端密钥)对用户进行身份验证并获取 Google 的 API 访问权限。

To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.

Or, view your client ID and client secret from the Credentials page in API Console:

  1. Go to the Credentials page.
  2. Click the name of your credential or the pencil () icon. Your client ID and secret are at the top of the page.

设置重定向 URI

您在 API Console 中设置的重定向 URI 决定了 Google 将响应发送到身份验证请求的位置。

要创建,查看或编辑给定OAuth 2.0凭据的重定向URI,请执行以下操作:

  1. Go to the Credentials page.
  2. 在页面的OAuth 2.0客户端ID部分中,点击一个凭据。
  3. 查看或编辑重定向URI。

如果“凭据”页面上没有OAuth 2.0客户端ID部分,则您的项目没有OAuth凭据。要创建一个,点击创建凭证

自定义用户同意屏幕

OAuth 2.0 身份验证体验针对用户而言,包含一个同意屏幕,其中会向用户披露所发布的信息和适用的条款。例如,当用户登录时,系统可能会要求他们向您的应用授予其电子邮件地址和基本帐号信息的访问权限。您可以使用 scope 参数(应用在其身份验证请求中包含此参数)来请求访问此信息。您还可以使用范围请求访问其他 Google API。

用户同意屏幕还会显示您的产品名称、徽标和首页网址等品牌信息。您可以在 API Console中控制品牌信息。

要启用项目的同意屏幕:

  1. Consent Screen page中打开Google API Console 。
  2. If prompted, select a project, or create a new one.
  3. 填写表格,然后点击保存

以下意见征求对话框显示了请求中存在 OAuth 2.0 和 Google 云端硬盘范围组合时用户将看到的内容。(此通用对话框是使用 Google OAuth 2.0 Playground 生成的,因此它不包含 API Console中设置的品牌信息。)

意见征求页面屏幕截图

访问服务

Google 和第三方提供了一些库,可用于处理对用户进行身份验证以及获取 Google API 访问权限的许多实现细节。示例包括适用于各种平台的 Google 登录Google 客户端库

如果您选择不使用库,请按照本文档其余部分(介绍了可用库下所含 HTTP 请求流程)的说明进行操作。

对用户进行身份验证

对用户进行身份验证涉及获取 ID 令牌和验证令牌。ID 令牌OpenID Connect 的标准化功能,旨在在互联网上共享身份断言。

最常用的验证用户身份和获取 ID 令牌的方法称为“服务器”流程和“隐式”流程。服务器流程允许应用的后端服务器使用浏览器或移动设备验证用户的身份。当客户端应用(通常是在浏览器中运行的 JavaScript 应用)需要直接访问应用而不通过其后端服务器访问 API 时,需要使用隐式流程。

本文档介绍如何执行服务器流程以对用户进行身份验证。由于在客户端处理和使用令牌存在安全风险,隐式流程要复杂得多。如果您需要实现隐式流程,我们强烈建议您使用 Google 登录

服务器流

请务必在 API Console中设置您的应用,使其能够使用这些协议并对用户进行身份验证。当用户尝试通过 Google 登录时,您需要执行以下操作:

  1. 创建防假冒状态令牌
  2. 向 Google 发送身份验证请求
  3. 确认防假冒状态令牌
  4. 交换 code 以获取访问令牌和 ID 令牌
  5. 从 ID 令牌中获取用户信息
  6. 对用户进行身份验证

1. 创建防假冒状态令牌

您必须通过防止请求伪造攻击来保障用户安全。第一步是创建唯一的会话令牌,以保存您的应用与用户客户端之间的状态。 稍后,您需要将此唯一会话令牌与 Google OAuth 登录服务返回的身份验证响应相匹配,以验证用户发出的是请求而不是恶意攻击者。这些令牌通常称为跨网站请求伪造 (CSRF) 令牌。

对于状态令牌,最好使用 30 个左右的字符字符串(即使用高质量随机数字生成器构建的字符)。另一个哈希是通过使用在后端保密的密钥为您的部分会话状态变量签名而生成的。

以下代码演示了如何生成唯一的会话令牌。

PHP

您必须下载适用于 PHP 的 Google API 客户端库才能使用此示例。

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

您必须下载适用于 Java 的 Google API 客户端库,才能使用此示例。

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

您必须下载适用于 Python 的 Google API 客户端库才能使用此示例。

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. 向 Google 发送身份验证请求

下一步是使用适当的 URI 参数形成 HTTPS GET 请求。请注意,在此过程中的所有步骤中均使用 HTTPS 而非 HTTP;HTTP 连接会被拒绝。您应使用 authorization_endpoint 元数据值从发现文档中检索基本 URI。以下讨论假定基础 URI 为 https://accounts.google.com/o/oauth2/v2/auth

对于基本请求,请指定以下参数:

  • client_id(从 API ConsoleCredentials page中获取)。
  • response_type,在基本授权代码流请求中应该是 code。(如需了解详情,请访问 response_type。)
  • scope,基本请求中应为 openid email。(如需了解详情,请访问 scope。)
  • redirect_uri 应该是您服务器上的 Google 端点,用于接收来自 Google 的响应。该值必须与您在 API ConsoleCredentials page中配置的 OAuth 2.0 客户端的某个已获授权的重定向 URI 完全一致。如果此值与已获授权的 URI 不匹配,请求将失败并显示 redirect_uri_mismatch 错误。
  • state 应包含防假冒唯一会话令牌的值,以及在用户返回到您的应用时恢复上下文所需的任何其他信息(例如起始网址)。(如需了解详情,请访问 state。)
  • nonce 是您的应用生成的一个随机值,启用重放保护。
  • login_hint 可以是用户的电子邮件地址,也可以是 sub 字符串,它相当于用户的 Google ID。如果您未提供 login_hint,并且用户当前处于登录状态,则同意屏幕中会显示一条批准请求,要求将用户的电子邮件地址发布到应用中。(如需了解详情,请访问 login_hint。)
  • 使用 hd 参数,针对与 Google Cloud 组织关联的特定网域的用户优化 OpenID Connect 流程。(如需了解详情,请访问 hd。)

以下是一个完整的 OpenID Connect 身份验证 URI 示例,其中有换行符和空格,以方便阅读:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

如果您的应用需要关于用户的任何新信息,或该应用之前从未批准过应用请求访问帐号,则需要征得用户同意。

3.确认防假冒状态令牌

响应会被发送到您在请求中指定的 redirect_uri。所有响应都在查询字符串中返回,如下所示:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

在服务器上,您必须确认从 Google 收到的 state 是否与您在第 1 步中创建的会话令牌匹配。这种往返验证有助于确保用户发出请求,而不是恶意脚本。

以下代码演示了如何确认您在第 1 步中创建的会话令牌:

PHP

您必须下载适用于 PHP 的 Google API 客户端库才能使用此示例。

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

您必须下载适用于 Java 的 Google API 客户端库,才能使用此示例。

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

您必须下载适用于 Python 的 Google API 客户端库才能使用此示例。

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4.使用 code 交换访问令牌和 ID 令牌

响应中包含 code 参数,您的服务器可用来交换访问令牌和 ID 令牌的一次性授权代码。您的服务器通过发送 HTTPS POST 请求进行此交换。POST 请求会发送到令牌端点,您应使用 token_endpoint 元数据值从发现文档中检索该端点。以下讨论假定端点为 https://oauth2.googleapis.com/token。请求必须在 POST 正文中包含以下参数:

字段
code 初始请求返回的授权代码。
client_id 您从 API ConsoleCredentials page获得的客户端 ID,如获取 OAuth 2.0 凭据中所述。
client_secret 您从 API ConsoleCredentials page获得的客户端密钥,如获取 OAuth 2.0 凭据中所述。
redirect_uri API ConsoleCredentials page中指定的给定 client_id 的授权重定向 URI,如设置重定向 URI 中所述。
grant_type 此字段必须包含 authorization_code, 的值,如 OAuth 2.0 规范所定义。

实际请求可能如下所示:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

此请求的成功响应包含一个 JSON 数组中的以下字段:

字段
access_token 可发送到 Google API 的令牌。
expires_in 访问令牌的剩余生命周期(以秒为单位)。
id_token JWT,其中包含由 Google 进行数字签名的用户的身份信息。
scope access_token 授予的访问权限范围,表示为以空格分隔且区分大小写的字符串列表。
token_type 标识返回的令牌类型。此时,此字段始终具有值 Bearer
refresh_token (可选)

只有在身份验证请求中的 access_type 参数设置为 offline 时,此字段才会显示。有关详情,请参阅刷新令牌

5. 从 ID 令牌中获取用户信息

ID 令牌是 JWT(JSON Web 令牌),即经过加密签名的 Base64 编码的 JSON 对象。通常,您必须在使用之前验证 ID 令牌,但由于您是通过无中间中介 HTTPS 渠道直接与 Google 通信,并使用客户端密钥向 Google 进行身份验证,因此您可以确信自己收到的令牌确实来自 Google 且有效。如果您的服务器将 ID 令牌传递给应用的其他组件,务必务必先让其他组件验证令牌,然后再使用。

由于大多数 API 库都会将验证与解码 base64url 编码值并解析 JSON 的工作相结合,因此,在访问 ID 令牌中的声明时,您最终仍可能需要验证令牌。

ID 令牌的载荷

ID 令牌是包含一组名称/值对的 JSON 对象。以下是一个示例,其格式便于阅读:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Google ID 令牌可能包含以下字段(称为声明):

Claim 已提供 说明
aud 始终 此 ID 令牌的目标受众群体。它必须是应用的 OAuth 2.0 客户端 ID 之一。
exp 始终 不得接受 ID 令牌的有效期。以 Unix 时间(整数秒数)表示。
iat 始终 ID 令牌的发放时间。以 Unix 时间(整数秒数)表示。
iss 始终 响应的发卡机构的发卡机构标识符。对于 Google ID 令牌,始终为 https://accounts.google.comaccounts.google.com
sub 始终 用户的标识符,在所有 Google 帐号中都是唯一的,并且不会重复使用。一个 Google 帐号在不同时间点可以有多个电子邮件地址,但 sub 值绝不会更改。在您的应用中使用 sub 作为用户的唯一标识符键。长度上限为 255 个区分大小写的 ASCII 字符。
at_hash 访问令牌哈希。提供访问令牌与身份令牌相关联的验证信息。如果在服务器流程中发出 ID 令牌值为 access_token,此声明始终会包含在其中。此声明可用作防范跨站请求伪造攻击的备用机制,但如果您执行第 1 步第 3 步,则无需验证访问令牌。
azp 授权演示者的 client_id。只有在 ID 令牌的请求方与 ID 令牌的受众群体不同时,才需要此声明。混合创收应用可能的情况就属于这种情况,这是因为 Web 应用和 Android 应用采用不同的 OAuth 2.0 client_id,但它们共用同一个 Google API 项目。
email 用户的电子邮件地址。此值可能并非该用户的唯一值,不适合用作主键。仅当您的范围包含 email 范围值时提供。
email_verified 如果用户的电子邮件地址已通过验证,则为 true;否则为 false。
family_name 用户的姓氏或名字。如果存在 name 声明,则可以提供。
given_name 用户的名字或名字。如果存在 name 声明,则可以提供。
hd 与用户 Google Cloud 单位关联的网域。仅当用户属于某个 Google Cloud 组织时提供。
locale 用户的语言区域,由 BCP 47 语言标记表示。如果存在 name 声明,则可以提供。
name 用户的全名,采用可显示的形式。在以下情况下,可能会提供:
  • 请求范围包括字符串“&profile”
  • 系统会通过刷新令牌返回 ID 令牌

如果存在 name 声明,您可以使用它们来更新应用的用户记录。请注意,我们无法保证此声明会一直存在。

nonce 您的应用在身份验证请求中提供的 nonce 值。您应确保它只出现一次,以防范重放攻击。
picture 用户个人资料照片的网址。在以下情况下,可能会提供:
  • 请求范围包括字符串“&profile”
  • 系统会通过刷新令牌返回 ID 令牌

如果存在 picture 声明,您可以使用它们来更新应用的用户记录。请注意,我们无法保证此声明会一直存在。

profile 用户个人资料页面的网址。在以下情况下,可能会提供:
  • 请求范围包括字符串“&profile”
  • 系统会通过刷新令牌返回 ID 令牌

如果存在 profile 声明,您可以使用它们来更新应用的用户记录。请注意,我们无法保证此声明会一直存在。

6. 对用户进行身份验证

从 ID 令牌中获取用户信息后,您应该查询应用的用户数据库。 如果数据库中已存在该用户,那么在 Google API 响应满足所有登录要求的情况下,您应该为该用户启动应用会话。

如果用户数据库中不存在此用户,您应该将用户重定向到新用户注册流程。您可以根据从 Google 收到的信息自动填充用户信息,或者至少可以预填充您在注册表单上要求填写的许多字段。除了 ID 令牌中的信息之外,您还可以在我们的用户个人资料端点获取其他用户个人资料信息

高级主题

以下部分更详细地介绍了 Google OAuth 2.0 API。本文面向的是对身份验证和授权有高级要求的开发者。

访问其他 Google API

使用 OAuth 2.0 进行身份验证的一个优点是,您的应用可以在您验证用户身份时,获得代表用户使用其他 Google API(例如 YouTube、Google 云端硬盘、日历或通讯录)的权限。为此,请在向 Google 发送的身份验证请求中添加您需要的其他范围。例如,如需将用户的年龄段添加到身份验证请求中,请传递 openid email https://www.googleapis.com/auth/profile.agerange.read 的范围参数。系统会在同意屏幕上提示用户。通过从 Google 接收的访问令牌,您可以访问与您请求并授予的访问权限范围相关的所有 API。

刷新令牌

在 API 访问权限请求中,您可以请求在 code 交换期间返回刷新令牌。刷新令牌可让您的应用持续访问 Google API,而无需用户出现在您的应用中。如需请求刷新令牌,请在身份验证请求中添加 access_type 参数,并将其设置为 offline

注意事项:

  • 请务必安全且永久存储刷新令牌,因为您只能在首次执行代码交换流程时获取刷新令牌。
  • 颁发的刷新令牌的数量有限:每个客户端/用户组合一个限制,而所有客户端上的每个用户都另一个限制。如果您的应用请求刷新令牌的次数过多,则可能会遇到这些限制,在这种情况下,较旧的刷新令牌会停止工作。

如需了解详情,请参阅刷新访问令牌(离线访问)

您可以在身份验证请求中将 prompt 参数设置为 consent,以提示用户重新授权您的应用。如果包含 prompt=consent,那么每当您的应用请求授权范围时就会显示同意屏幕,即使之前已向您的 Google API 项目授予所有范围也是如此。因此,请仅在必要时添加 prompt=consent

如需详细了解 prompt 参数,请参阅身份验证 URI 参数表格中的 prompt

身份验证 URI 参数

下表更全面地介绍了 Google OAuth 2.0 身份验证 API 接受的参数。

参数 必需 说明
client_id (必填) 您从 API ConsoleCredentials page获取的客户端 ID 字符串,如获取 OAuth 2.0 凭据中所述。
nonce (必填) 您的应用生成的用于启用重放保护的随机值。
response_type (必填) 如果值为 code,则会启动基本授权代码流,需要 POST 到令牌端点以获取令牌。如果值为 token id_tokenid_token token,则启动隐式流,要求在重定向 URI 中使用 JavaScript 从 URI #fragment 标识符中检索令牌。
redirect_uri (必填) 确定响应的发送位置。此参数的值必须与您在 API ConsoleCredentials page 中设置的某个已获授权的重定向值完全匹配(包括 HTTP 或 HTTPS 架构、大小写、尾随 '/' ,如有)。
scope (必填)

范围参数必须以 openid 值开头,然后包含 profile 值和/或 email 值。

如果存在 profile 范围值,ID 令牌可能会(但不保证)包含用户的默认 profile 声明。

如果存在 email 范围值,则 ID 令牌包含 emailemail_verified 声明。

除了这些特定于 OpenID 的范围之外,您的范围参数还可以包含其他范围值。所有范围值都必须用空格分隔。例如,如果您需要按文件访问用户的 Google 云端硬盘,则您的范围参数可能是 openid profile email https://www.googleapis.com/auth/drive.file

如需了解可用范围,请参阅适用于 Google API 的 OAuth 2.0 范围或您要使用的 Google API 文档。

state (可选,但强烈建议)

协议中往返的不透明字符串;也就是说,它会作为 URI 参数在基本流以及隐式流中以 URI #fragment 标识符返回。

state 有助于关联请求和响应。由于您的 redirect_uri 是可以猜测的,因此使用 state 值可确保传入的连接是应用发起的身份验证请求的结果。如果您生成随机字符串或在此 state 变量中对某个客户端状态(例如 Cookie)的哈希值进行编码,则可以验证响应以进一步确保请求和响应来自同一浏览器。这有助于防范跨站请求伪造等攻击。

access_type (选填) 允许的值为 offlineonline。该效果记录在离线访问中;如果请求的是访问令牌,则客户端不会收到刷新令牌,除非指定的值为 offline
display (选填) ASCII 字符串值,用于指定授权服务器如何显示身份验证和用户意见征求界面。指定以下值并由 Google 服务器接受,但对它们的行为没有任何影响:pagepopuptouchwap
hd (选填)

简化 Google Cloud 单位拥有的帐号的登录流程。通过添加 Google Cloud 组织网域(例如 mycollege.edu),您可以指示应针对该网域中的帐号优化帐号选择界面。如需通常针对 Google Cloud 组织帐号(而不仅仅是一个 Google Cloud 组织网域)进行优化,请设置一个星号 (*) 值:hd=*

不要依赖此界面优化来控制谁能够访问您的应用,因为客户端请求可以修改。请务必验证返回的 ID 令牌hd 声明值是否符合您的预期(例如 mycolledge.edu)。与请求参数不同,ID 令牌 hd 声明包含在 Google 的安全令牌中,因此,该值可以可信。

include_granted_scopes (选填) 如果将该参数提供给值 true,且授权请求已获授权,则授权将包括之前针对其他范围授予此用户/应用组合的所有授权。请参阅增量授权

请注意,您无法通过“已安装的应用”流程进行增量授权。

login_hint (选填) 当您的应用知道自己正尝试对哪个用户进行身份验证时,它可以将此参数作为提示提供给身份验证服务器。传递此提示会抑制帐号选择器,并在登录表单上预填充电子邮件地址,或选择适当的会话(如果用户使用多帐号登录),这有助于避免您的应用登录错误的用户帐号时发生问题。 值可以是电子邮件地址或 sub 字符串,相当于用户的 Google ID。
prompt (选填) 以空格分隔的字符串值列表,用于指定授权服务器是否提示用户重新进行身份验证和表示同意。可能的值包括:
  • none

    授权服务器不会显示任何身份验证或用户同意屏幕;如果用户尚未通过身份验证且未针对请求的范围预先配置同意,则服务器将返回错误。您可以使用 none 检查现有身份验证和/或用户意见征求。

  • consent

    授权服务器会在将信息返回客户端之前提示用户同意。

  • select_account

    授权服务器会提示用户选择用户帐号。这样,在授权服务器中具有多个帐号的用户就可以从他们可能拥有当前会话的多个帐号中选择。

如果未指定任何值,并且用户之前未授予访问权限,则系统会向用户显示同意屏幕。

验证 ID 令牌

除非您确认这些 ID 令牌直接来自 Google,否则您需要验证服务器上的所有 ID 令牌。例如,您的服务器必须验证从客户端应用收到的所有 ID 令牌是否真实。

以下是您可能会向服务器发送 ID 令牌的常见情况:

  • 发送需要进行身份验证的请求的 ID 令牌。通过 ID 令牌,您可以了解发出请求的特定用户以及向其授予该 ID 令牌的客户端。

ID 令牌属于敏感信息,如果被拦截,可能会被滥用。您必须确保仅通过 HTTPS 传输这些令牌,并仅通过 POST 数据或在请求标头内安全地处理这些令牌。如果您将 ID 令牌存储在服务器上,那么您还必须安全地存储这些令牌。

让 ID 令牌发挥作用的一点是,您可以将它们传递给应用的不同组件。这些组件可以将 ID 令牌用作轻量级身份验证机制,对应用和用户进行身份验证。但是,您必须先验证此 ID,然后才能使用该 ID 令牌中的信息或将其用作用户已通过身份验证的断言。

验证 ID 令牌需要以下几个步骤:

  1. 验证发卡机构签发的 ID 令牌是否正确。Google 签发的令牌使用在发现文档jwks_uri 元数据值中指定的 URI 处获得的证书进行签名。
  2. 验证 ID 令牌中 iss 声明的值等于 https://accounts.google.comaccounts.google.com
  3. 验证 ID 令牌中 aud 声明的值等于应用的客户端 ID。
  4. 验证 ID 令牌的有效期(exp 个声明)未过。
  5. 如果您在请求中指定了 hd parameter 值,请验证 ID 令牌是否具有与 Google Cloud 组织关联的接受网域匹配的 hd 声明。

第 2 步到第 5 步仅涉及非常简单的字符串和日期比较,因此我们不会在此处详细介绍。

第一步更为复杂,涉及加密签名检查。出于调试目的,您可以使用 Google 的 tokeninfo 端点与您的服务器或设备上实施的本地处理进行比较。假设您的 ID 令牌值为 XYZ123,然后,将解引用 URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123。如果令牌签名有效,则响应将为已解码 JSON 对象形式的 JWT 载荷。

tokeninfo 端点可用于调试,但出于生产目的,请从密钥端点检索 Google 的公钥,并在本地执行验证。您应该使用 jwks_uri 元数据值从发现文档中检索键 URI。对调试端点的请求可能会受到限制或受到间歇性错误的影响。

由于 Google 不会频繁更改公钥,因此您可以使用 HTTP 响应的缓存指令对其进行缓存,在绝大多数情况下,与使用 tokeninfo 端点相比,可以更高效地执行本地验证。此验证需要检索和解析证书,并执行适当的加密调用以检查签名。幸运的是,有多种经过调试的库可用于多种语言(请参阅 jwt.io)。

获取用户个人资料信息

要获取有关用户的其他个人资料信息,您可以使用访问令牌(应用在身份验证流程期间收到)和 OpenID Connect 标准:

  1. 为了符合 OpenID 标准,您必须在身份验证请求中添加 openid profile 范围值。

    如果要包含用户的电子邮件地址,可指定额外范围值 email。 要同时指定 profileemail,您可以在身份验证请求 URI 中添加以下参数:

    scope=openid%20profile%20email
  2. 将您的访问令牌添加到授权标头中,并向 userinfo 端点发出 HTTPS GET 请求,您应该使用 userinfo_endpoint 元数据值从发现文档中检索该令牌。userinfo 响应包含用户的相关信息,如 OpenID Connect Standard Claims 和发现文档的 claims_supported 元数据值中所述。用户或其组织可能会选择提供或拒绝某些字段,因此您可能无法获得授权访问范围的每个字段的信息。

Discovery 文档

OpenID Connect 协议要求使用多个端点对用户进行身份验证以及请求资源(包括令牌、用户信息和公钥)。

为了简化实现并提高灵活性,OpenID Connect 允许使用位于以下位置的 JSON 文档:发现文档包含有关 OpenID Connect 提供商配置的详细信息,包括授权、令牌、撤消、用户信息、公钥端点的 URI。可从以下产品检索 Google OpenID Connect 服务的发现文档:

https://accounts.google.com/.well-known/openid-configuration

如需使用 Google' OpenID Connect 服务,您应该将发现文档 URI (https://accounts.google.com/.well-known/openid-configuration) 硬编码到您的应用中。 您的应用提取文档,在响应中应用缓存规则,然后根据需要从该文档检索端点 URI。例如,为了对用户进行身份验证,您的代码会检索 authorization_endpoint 元数据值(以下示例中的 https://accounts.google.com/o/oauth2/v2/auth)作为发送给 Google 的身份验证请求的基本 URI。

以下是此类文档的示例;字段名称是 OpenID Connect Discovery 1.0 中指定的字段(如需了解具体含义,请参阅该文档)。 这些值仅用于说明,并可能会更改,尽管它们是从实际版本的 Google 探索文档的最新版本复制而来:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

您可以通过缓存发现文档中的值来避免 HTTP 往返。使用的是标准 HTTP 缓存标头,应该采用这种标头。

客户端库

以下客户端库与热门框架集成,简化了 OAuth 2.0 的实现:

OpenID Connect 合规性

Google 的 OAuth 2.0 身份验证系统支持 OpenID Connect Core 规范的所需功能。 旨在与 OpenID Connect 配合使用的任何客户端都应与此服务互操作(OpenID 请求对象除外)。