OpenID 连接

谷歌的OAuth 2.0的API可用于身份验证和授权。本文介绍了我们的OAuth 2.0实现了身份验证，这符合ID连接规范，是OpenID的认证。中找到的文档使用OAuth 2.0访问谷歌的API也适用于此项服务。如果你想以交互方式探索这个协议，我们建议谷歌的OAuth 2.0游乐场。要获得帮助堆栈溢出，与“谷歌的OAuth”标记您的问题。

设置的OAuth 2.0

在应用程序能够使用谷歌的OAuth 2.0认证系统，用户登录，您必须设置一个项目在 Google API Console 获得的OAuth 2.0凭据，请设置一个重定向URI和（可选）定制品牌信息，您的用户在看到用户同意画面。您也可以使用 API Console 创建一个服务帐户，使计费，设置过滤，以及执行其他任务。有关详细信息，请参阅Google API Console帮助。

获取OAuth 2.0凭证

您需要OAuth 2.0凭证，包括客户端ID和客户端密钥，对用户进行认证并获得谷歌的API。

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

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

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

设置一个重定向URI

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

要创建，查看或编辑给定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参数，您的应用包括在它的认证请求。您还可以使用范围向其他谷歌API的请求访问。

用户同意画面也呈现品牌信息，如产品名称，标识和主页URL。您可以控制在了品牌信息 API Console。

要启用项目的同意屏幕：

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

以下同意对话框将显示用户将看到的，当OAuth 2.0用户和谷歌驱动范围的组合出现在请求中。 （用的是产生这种通用对话框谷歌的OAuth 2.0游乐场，所以它不包括将在设定品牌信息 API Console。）

访问服务

谷歌和第三方提供的库，您可以使用采取很多的用户进行身份验证并获得访问谷歌的API的实现细节的照顾。例子包括谷歌登录在与谷歌客户端库，它可用于各种平台。

如果您不选择在这个文件，它描述了HTTP请求的其余部分使用一个库，按照说明流动是underly可用库。

认证用户

认证所述用户包括获得ID令牌和验证它。 ID令牌是一个标准化特征ID连接设计用在互联网上共享的身份断言。

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

本文介绍如何执行对用户进行认证的服务器流量。隐式流量显著更加复杂，因为在处理与客户端上使用令牌的安全隐患。如果您需要实现一个隐含的流程，我们强烈建议您使用谷歌登录的帐户。

服务器流量

请确保您设置在您的应用程序 API Console以使其能够使用这些协议和验证用户。当用户试图登录在与谷歌，您需要：

1. 创建一个防伪标记状态
2. 发送验证请求，以谷歌
3. 确认防伪状态令牌
4. 交易所code的访问令牌和ID令牌
5. 获得从ID令牌的用户信息
6. 认证用户

1.创建一个防伪标记状态

你必须通过防止请求伪造攻击，保护用户的安全。第一步是创建您的应用程序和用户的客户端之间保持状态的唯一的会话令牌。你以后搭配由谷歌的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.发送认证请求，谷歌

下一步是形成HTTPS GET与适当的URI参数的请求。注意使用HTTPS而不是HTTP在这个过程中的所有步骤; HTTP连接将被拒绝。你应该检索的基础URI发现文档使用authorization_endpoint元数据值。下面的讨论假定基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应该是HTTP端点服务器将收到来自谷歌的反应上。该值必须完全匹配授权的重定向的URI的OAuth 2.0用户端，你的配置的一个 API ConsoleCredentials page。如果此值不匹配授权的URI，请求将失败， redirect_uri_mismatch错误。
• state应包括防伪唯一的会话令牌的价值，以及恢复的背景下，当用户返回到您的应用程序，例如，起始URL所需的任何其他信息。 （更多内容请见state 。）
• nonce是由你的应用程序生成的随机值，使当重放保护存在。
• login_hint可以是用户的电子邮件地址或sub串，这相当于用户的谷歌ID。如果你不提供login_hint ，目前用户已登录，同意画面包括批准发布用户的电子邮件地址，你的应用程序的请求。 （更多login_hint 。）
• 使用hd参数，以优化与谷歌云组织相关的特定域的用户ID连接流。 （更多内容hd ）。

这是一个完整的ID连接验证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

在服务器上，你必须确认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网络令牌），即，一个密码签名Base64编码JSON对象。通常情况下，关键是你验证ID令牌在使用它之前，但因为你是直接与谷歌经由中间无HTTPS通道通信并使用您的客户端密钥对自己进行身份验证，以谷歌，你可以确信令牌你真的收到来自谷歌和有效。如果你的服务器通过令牌您的应用程序的其他组件的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"
}

谷歌ID令牌可以包含以下字段（称为索赔）：

6.认证用户

获得从ID令牌的用户信息后，您应查询您的应用程序的用户数据库。如果用户在数据库中已经存在，你应该如果所有登录要求由谷歌API响应满足用户启动应用程序会话。

如果用户没有在您的用户数据库中，你应该将用户重定向到新的用户注册流程。您可能能够自动根据登记的信息，你从谷歌收到，或者至少是你可以预先填入许多领域，你需要你的登记表上的用户。除了在ID令牌的信息，您可以得到更多的用户配置文件信息，在我们的用户配置文件端点。

高级主题

以下各节更详细地描述了谷歌的OAuth 2.0 API。此信息用于与周围的认证和授权高级的需求开发。

访问其他谷歌的API

一个使用OAuth 2.0认证的好处是，你的应用程序可以获得许可，为您验证用户在同一时间代表用户（如YouTube，谷歌云端硬盘，日历或联系人）的使用其他谷歌的API。要做到这一点，包括其他领域，你在需要的认证请求您发送给谷歌。例如，用户的年龄组添加到您的认证请求，传递的范围参数openid email https://www.googleapis.com/auth/profile.agerange.read 。用户适当提示上同意画面。令牌您收到来自谷歌背后的通道允许您访问所有相关访问的您请求并授予范围的API。

刷新令牌

在您的要求为API访问权限，你可以请求刷新令牌时将返回code交换。刷新而用户没有出现在你的应用程序令牌来提供你的应用程序不间断地访问谷歌的API。要请求刷新令牌，加设置access_type参数offline在您的认证请求。

注意事项：

• 一定要安全地存储并永久令牌刷新，因为你只能获得一个刷新令牌第一次执行的代码交换流量。
• 有上发出该刷新令牌的数量限制：每个客户端/用户组合中的一个限制，每跨所有客户端用户的另一个。如果你的应用程序请求太多刷新令牌，它可能会碰到这些限制，在这种情况下，旧的刷新令牌停止工作。

欲了解更多信息，请参阅刷新令牌（离线访问）的访问。

提示重新同意

您可以提示用户通过设置重新授权您的应用程序的prompt参数来consent你的认证请求。当prompt=consent包括，同意画面，显示每个您的应用程序请求访问的范围的授权时，即使所有范围先前授予给您的谷歌API的项目。出于这个原因，包括prompt=consent只在必要时。

欲了解更多有关的prompt参数，请参阅prompt在验证URI参数表。

验证URI参数

下表给出了谷歌的OAuth 2.0认证API接受的参数更全面的说明。

验证ID令牌

您需要验证您的服务器上的所有ID令牌，除非你知道它们直接来自谷歌。例如，您的服务器必须验证为正品任何ID令牌是从客户端应用程序接收。

以下是在那里你可以发送ID令牌服务器常见的情况：

• 发送ID令牌与需要进行身份验证请求。该ID令牌告诉你发出请求的特定用户和其客户端ID令牌被授予。

ID标记是敏感的，如果拦截可能被滥用。你必须确保这些令牌仅通过HTTPS而且只能通过POST数据或请求头中发送他们安全的处理。如果存储在服务器上的ID令牌，你也必须存储紧。

有一两件事，使ID令牌有用的是事实，你可以通过他们你的应用程序的各地不同的组件。这些组件可以使用令牌为轻量级认证机制认证所述应用程序和用户的ID。但在此之前，你可以在ID使用信息令牌或依靠它作为断言用户身份验证，则必须对其进行验证。

一个ID令牌的确认需要几个步骤：

1. 验证ID令牌妥善由发行人签署。谷歌发出的令牌使用证书之一中发现的URI中指定的jwks_uri中的元数据价值发现的文件。
2. 验证的值iss在ID令牌权利要求等于https://accounts.google.com或accounts.google.com 。
3. 确认的价值aud在ID令牌要求等于你的应用程序的客户端ID。
4. 验证到期时间（ exp ID令牌的权利要求）没有通过。
5. 如果指定了高清的参数中的请求值，验证ID令牌具有hd要求匹配与谷歌云组织相关联的接受域。

步骤2至5只涉及字符串和日期比较这是非常简单的，所以我们不会在这里详细介绍它们。

第一步是比较复杂，涉及到加密签名检查。为了调试的目的，你可以使用谷歌的tokeninfo端点比较对您的服务器或设备上实现就地加工。假设你的ID令牌的值是XYZ123 。然后，你会取消引用URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 。如果令牌签名是有效的，他们的回应是在其解码JSON对象的形式JWT有效载荷。

该tokeninfo终点是用于调试，但用于生产目的有用，检索键谷歌的公共密钥终端和本地执行验证。你应该检索来自键URI发现文档使用jwks_uri元数据值。请在调试端点可节流或受间歇性错误。

由于谷歌改变其公钥只是偶尔，你可以使用HTTP响应的缓存指令缓存他们，在绝大多数情况下，更有效地进行本地验证比使用tokeninfo端点。此验证需要检索和分析证书，并进行适当的加密电话来检查签名。在各种各样的语言幸好还有完善的调试库，以实现这一目标（见jwt.io ）。

获取用户的个人资料信息

要获得有关用户的其他个人资料信息，您可以使用访问令牌（在此期间您的应用程序接收到认证流程）和ID连接标准：

1. 为了OpenID的标准，你必须包括OpenID的openid profile在你的范围值验证请求。

   如果您要包括用户的电子邮件地址，你可以指定一个额外的范围值的email 。同时指定profile和email ，您可以在您的认证请求的URI以下参数：

   scope=openid%20profile%20email

2. 添加令牌授权头您的访问并作出HTTPS GET请求给用户信息终端，你应该从检索发现文档使用userinfo_endpoint元数据值。用户信息响应包括关于该用户的，在如所描述的信息ID OpenID Connect Standard Claims和claims_supported愉文件的元数据值。用户或他们的组织可以选择供应或隐瞒某些字段，所以您可能无法访问您的授权范围得到各个领域的信息。

该发现文件

该ID连接协议，需要进行用户认证，并请求资源，包括令牌，用户信息和公共密钥使用多个端点。

为了简化实现，并增加柔韧性，ID连接允许使用“发现文件”的JSON文档在含有键 - 值对，其提供关于ID连接提供商的配置的详细信息，包括授权的URI的一个众所周知的位置发现，令牌，撤销，用户信息和公共密钥端点。谷歌的ID连接服务发现文档可以从检索：

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

使用谷歌的ID连接服务，你应该硬编码的发现文档URI（ https://accounts.google.com/.well-known/openid-configuration ）到应用程序中。你的应用程序读取该文件，适用于响应缓存规则，然后根据需要从它检索端点的URI。例如，为了用户进行认证，您的代码将检索authorization_endpoint元数据值（ https://accounts.google.com/o/oauth2/v2/auth在下面的例子中），其被发送到基本URI认证请求谷歌。

下面是这样一个文件的例子;字段名称是那些在指定的ID连接发现1.0 （参照该文献为它们的含义）。该值仅是说明性的，可能会改变，但他们是从最新版本的谷歌实际发现文档的复制：

{
  "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简单的用流行的框架整合：

• 谷歌API客户端库的Java
• 谷歌API客户端库的Python
• 谷歌API客户端库.NET
• 谷歌API客户端库的Ruby
• 谷歌API客户端库PHP
• 的OAuth 2.0库谷歌Web工具包
• 谷歌工具箱为Mac的OAuth 2.0控制器

ID连接达标

谷歌的OAuth 2.0认证系统支持所需的功能中的ID连接核心规范。其目的是与ID连接工作的任何客户端应该与此服务（与外互操作的OpenID请求对象）。