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 身份验证系统进行用户登录之前，您必须在 中设置一个项目，以获取 OAuth 2.0 凭据、设置重定向 URI，并（可选）自定义用户在用户意见征求界面上看到的品牌信息。您还可以使用 创建服务账号、启用结算、设置过滤条件以及执行其他任务。如需了解详情，请参阅 帮助。

获取 OAuth 2.0 凭据

您需要 OAuth 2.0 凭据（包括客户端 ID 和客户端密钥），才能对用户进行身份验证并获得对 Google API 的访问权限。

设置重定向 URI

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

自定义用户同意屏幕

对于用户而言，OAuth 2.0 身份验证体验包括一个意见征求界面，其中会说明用户要提供的信息以及适用的条款。例如，当用户登录时，系统可能会要求他们向您的应用授予对其电子邮件地址和基本账号信息的访问权限。您可以使用 scope 参数请求访问此类信息，您的应用会在身份验证请求中添加此参数。您还可以使用镜重范围请求访问其他 Google API。

用户意见征求界面还会显示品牌信息，例如产品名称、徽标和首页网址。您可以控制 中的品牌信息。

以下意见征求对话框展示了当请求中同时包含 OAuth 2.0 和 Google 云端硬盘范围时，用户会看到的内容。（此通用对话框是使用 Google OAuth 2.0 Playground 生成的，因此不包含要在 中设置的品牌信息。）

访问服务

Google 和第三方提供了一些库，您可以使用这些库来处理验证用户身份和获得对 Google API 的访问权限的许多实现细节。例如，适用于各种平台的 Google Identity 服务和 Google 客户端库。

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

对用户进行身份验证

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

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

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

服务器流程

请务必在 中设置您的应用，以便其使用这些协议并对用户进行身份验证。当用户尝试使用 Google 账号登录时，您需要：

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

1. 创建防伪造状态令牌

您必须通过防范请求伪造攻击来保护用户的安全。第 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，您可以从 中获取。
• response_type，在基本授权代码流程请求中，此值应为 code。（如需了解详情，请参阅 response_type。）
• scope，在基本请求中应为 openid email。 （如需了解详情，请参阅 scope。）
• redirect_uri 应为您服务器上用于接收 Google 响应的 HTTP 端点。此值必须与 OAuth 2.0 客户端的已获授权重定向 URI 之一完全匹配，该 URI 是在 中配置的。如果此值与已获授权的 URI 不匹配，请求将失败并显示 redirect_uri_mismatch 错误。
• state 应包含防伪唯一会话令牌的值，以及在用户返回您的应用时恢复上下文所需的任何其他信息，例如起始网址。 （如需了解详情，请参阅 state。）
• nonce 是应用生成的随机值，用于启用重放攻击防范功能（如果存在）。
• login_hint 可以是用户的电子邮件地址，也可以是 sub 字符串，该字符串相当于用户的 Google ID。如果您未提供 login_hint，并且用户当前已登录，则意见征求页面会包含一个请求，要求批准向您的应用提供用户的电子邮件地址。如需了解详情，请参阅 login_hint。
• 使用 hd 参数可为与 Google Workspace 或 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 令牌，然后才能使用它，但由于您是通过无中介的 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。

注意事项：

• 请务必安全地永久存储刷新令牌，因为您只能在首次执行代码交换流程时获取刷新令牌。
• 系统对发出的刷新令牌数量有限制：每个客户端/用户组合有 1 个限制，所有客户端中的每个用户还有一个限制。如果您的应用请求的刷新令牌过多，可能会遇到这些限制，在这种情况下，较早的刷新令牌将停止工作。

如需了解详情，请参阅刷新访问令牌（离线访问）。

提示重新同意

您可以在身份验证请求中将 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 令牌是授予哪个客户端的。

ID 令牌是敏感信息，如果被拦截，可能会被滥用。您必须确保以安全的方式处理这些令牌，方法是仅通过 HTTPS 传输这些令牌，并且仅通过 POST 数据或在请求标头中传输。如果您将 ID 令牌存储在服务器上，则还必须安全地存储这些令牌。

ID 令牌的一个实用之处在于，您可以将其传递到应用的不同组件。这些组件可以使用 ID 令牌作为轻量级身份验证机制来验证应用和用户。不过，您必须先验证 ID 令牌中的信息，或将其用作用户已完成身份验证的断言，然后才能使用这些信息。

验证 ID 令牌需要完成以下几个步骤：

1. 验证 ID 令牌是否由颁发者正确签名。Google 签发的令牌使用 发现文档的 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 步仅涉及字符串和日期比较，这些比较非常简单，因此我们不会在此详细介绍。

第 1 步更复杂，涉及加密签名检查。出于调试目的，您可以使用 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 中所述的用户信息，以及发现文档的 claims_supported 元数据值。用户或其所在组织可以选择提供或隐藏某些字段，因此您可能无法获得您已获授权访问范围的每个字段的信息。

发现文档

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

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

符合 OpenID Connect 要求

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