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 中设置项目，以便获取 OAuth 2.0 凭据、设置重定向 URI，以及（可选）自定义用户在用户意见征求屏幕上看到的品牌信息，然后您的应用才能使用 Google 的 OAuth 2.0 身份验证系统登录。 Google API Console 您还可以使用 API Console 创建服务帐号、启用结算功能、设置过滤以及执行其他任务。如需了解详情，请参阅 Google API Console帮助。

获取 OAuth 2.0 凭据

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

要查看给定OAuth 2.0凭据的客户端ID和客户端密钥，请单击以下文本： 选择凭据 。在打开的窗口中，选择您的项目和所需的凭证，然后单击“ 查看” 。

或者，从API Console的“ 凭据”页面中查看您的客户端ID和客户端密钥：

1. Go to the Credentials page.
2. 单击您的凭证名称或铅笔（ create ）图标。您的客户ID和密码位于页面顶部。

设置重定向 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 Identity Services 和 Google 客户端库。

如果您选择不使用库，请按照本文档其余部分中的说明操作，该部分介绍了底层库下的 HTTP 请求流程。

对用户进行身份验证

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

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

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

服务器流程

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

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

1. 创建反伪造状态令牌

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

状态令牌的一个好选择是使用高品质随机数生成器构造的大约 30 个字符的字符串。另一种方法是使用保存在后端的密钥对部分会话状态变量进行签名，从而生成哈希。

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

// 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
));

// 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);

# 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 响应的 HTTP 端点。该值必须与您在 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 步中创建的会话令牌：

// 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);
}

// 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.");
}

# 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 正文中添加以下参数：

实际请求可能如下所示：

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 数组中的字段：

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

ID 令牌是 JWT（JSON Web 令牌），即经过加密签名的 Base64 编码的 JSON 对象。通常，您在使用 ID 令牌之前必须先验证 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 令牌可能包含以下字段（称为声明）：

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 接受的参数。

验证 ID 令牌

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

在下列情况下，您可能会向服务器发送 ID 令牌：

• 发送 ID 令牌，其中包含需要进行身份验证的请求。通过 ID 令牌，您可以了解发出请求的特定用户以及获得了哪个 ID 令牌。

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

让 ID 令牌发挥作用的一个因素是，您可以在应用的不同组件之间传递这些 ID。这些组件可以将 ID 令牌用作轻量级身份验证机制来验证应用和用户。不过，您必须先验证 ID 令牌中的信息，或将其用作用户已通过身份验证的断言，然后才能使用这些信息。

验证 ID 令牌需要执行几个步骤：

1. 验证 ID 令牌是否已由发卡机构正确签名。由 Google 颁发的令牌使用在 Discovery 文档的 jwks_uri 元数据值中指定的 URI 处获得的证书进行签名。
2. 验证 ID 令牌中 iss 声明的值等于 https://accounts.google.com 或 accounts.google.com。
3. 验证 ID 令牌中 aud 声明的值等于应用的客户端 ID。
4. 验证 ID 令牌的有效期（exp 声明）未过。
5. 如果您在请求中指定了 hd 参数值，请验证 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。如需同时指定 profile 和 email，您可以在身份验证请求 URI 中添加以下参数：

   scope=openid%20profile%20email

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

发现文档

OpenID Connect 协议使用多个端点来验证用户身份以及请求资源（包括令牌、用户信息和公钥）。

为了简化实现并提高灵活性，OpenID Connect 允许使用“Discovery”文档，该文档位于一个众所周知的位置，包含键值对，可提供 OpenID Connect 提供方的配置详细信息，包括授权、令牌、撤消、userinfo 和公钥端点的 URI。可以从以下位置检索 Google OpenID Connect 服务的 Discovery 文档：

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 Discovery 文档的最新版本，但也可能会有所不同：

{
  "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 的实现：

• 适用于 Java 的 Google API 客户端库
• 适用于 Python 的 Google API 客户端库
• 适用于 .NET 的 Google API 客户端库
• 适用于 Ruby 的 Google API 客户端库
• 适用于 PHP 的 Google API 客户端库
• 适用于 Google Web Toolkit 的 OAuth 2.0 库
• 适用于 Mac OAuth 2.0 控制器的 Google 工具箱

OpenID Connect 合规性

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