本文档介绍了 Web 服务器应用如何使用 Google API 客户端库或 Google OAuth 2.0 端点来实现 OAuth 2.0 授权,以便访问 YouTube Data API。
OAuth 2.0 允许用户与应用共享特定数据,同时确保用户名、密码和其他信息的私密性。例如,应用可以使用 OAuth 2.0 获取将视频上传到用户的 YouTube 频道的权限。
此 OAuth 2.0 流程专门用于用户授权。它专为可存储机密信息和维护状态的应用而设计。经过适当授权的 Web 服务器应用可以在用户与应用交互或离开应用后访问 API。
Web 服务器应用也经常使用
服务帐号向 API 请求授权,特别是在调用 Cloud API 以访问基于项目的数据(而不是特定于用户的数据)时。Web 服务器应用可以将服务帐号与用户授权结合使用。
请注意,YouTube Data API 仅支持拥有并管理多个 YouTube 频道的 YouTube 内容所有者的服务账号流程。具体来说,内容所有者可以使用服务帐号调用支持 onBehalfOfContentOwner
请求参数的 API 方法。
客户端库
本页针对特定语言的示例使用 Google API 客户端库来实现 OAuth 2.0 授权。如需运行代码示例,您必须先安装适用于您的语言的客户端库。
当您使用 Google API 客户端库处理应用的 OAuth 2.0 流程时,客户端库会执行很多原本需要由应用自行处理的操作。例如,它确定应用何时可以使用或刷新存储的访问令牌,以及应用何时必须重新征得用户同意。客户端库还可生成正确的重定向网址,并有助于实现使用授权代码换取访问令牌的重定向处理程序。
适用于服务器端应用的 Google API 客户端库支持以下语言:
前提条件
为您的项目启用 API
任何调用 Google API 的应用都需要在 API Console中启用这些 API。
如需为您的项目启用该 API,请按以下步骤操作:
- Open the API Library (在 Google API Console中)。
- If prompted, select a project, or create a new one.
- 请使用库页面查找并启用 YouTube Data API。查找您的应用将使用的任何其他 API,并启用它们。
创建授权凭据
任何使用 OAuth 2.0 访问 Google API 的应用都必须具有授权凭据,用于向 Google 的 OAuth 2.0 服务器标识应用。以下步骤说明了如何为项目创建凭据。然后,您的应用就可以使用这些凭据访问已为该项目启用的 API。
- Go to the Credentials page.
- 依次点击创建凭据 > OAuth 客户端 ID。
- 选择 Web 应用应用类型。
- 填写表单,然后点击创建。使用 PHP、Java、Python、Ruby 和 .NET 等语言和框架的应用必须指定经授权的重定向 URI。重定向 URI 是 OAuth 2.0 服务器可向其发送响应的端点。这些端点必须遵守 Google 的验证规则。
对于测试,您可以指定引用本地机器的 URI,例如
http://localhost:8080
。考虑到这一点,请注意,本文档中的所有示例都使用http://localhost:8080
作为重定向 URI。我们建议您设计应用的身份验证端点,以免应用向网页上的其他资源公开授权代码。
创建凭据后,从 API Console下载 client_secret.json 文件。将文件安全地存储在只有您的应用可以访问的位置。
确定访问权限范围
借助范围,您的应用可以仅请求访问所需的资源,同时还能让用户控制他们向您的应用授予的访问权限大小。因此,请求的范围数量与征得用户同意的可能性之间可能存在反向关系。
在开始实现 OAuth 2.0 授权之前,我们建议您先确定您的应用需要访问权限的范围。
我们还建议您的应用通过增量授权流程请求对授权范围的访问权限,在该流程中,应用会在上下文中请求访问用户数据。此最佳实践可帮助用户更轻松地理解您的应用为何需要其请求的访问权限。
YouTube Data API v3 使用以下范围:
瞄准镜 | |
---|---|
https://www.googleapis.com/auth/youtube | 管理您的 YouTube 帐号 |
https://www.googleapis.com/auth/youtube.channel-memberships.creator | 查看包含以下信息的列表:当前活跃的频道会员、其当前级别以及其成为会员的时间 |
https://www.googleapis.com/auth/youtube.force-ssl | 查看、修改以及永久删除您的 YouTube 视频、评分、评论和字幕 |
https://www.googleapis.com/auth/youtube.readonly | 查看您的 YouTube 帐号 |
https://www.googleapis.com/auth/youtube.upload | 管理您的 YouTube 视频 |
https://www.googleapis.com/auth/youtubepartner | 查看和管理您在 YouTube 上的资源和关联内容 |
https://www.googleapis.com/auth/youtubepartner-channel-audit | 查看您的 YouTube 频道中关于 YouTube 合作伙伴试演的隐私信息 |
OAuth 2.0 API 范围文档包含可用于访问 Google API 的范围的完整列表。
特定语言的要求
如需运行本文档中的任何代码示例,您需要拥有 Google 帐号、互联网访问权限和网络浏览器。如果您使用的是某个 API 客户端库,还请参阅下面针对语言的要求。
PHP
如需运行本文档中的 PHP 代码示例,您需要:
- 安装了命令行界面 (CLI) 和 JSON 扩展程序的 PHP 5.6 或更高版本。
- Composer 依赖项管理工具。
-
适用于 PHP 的 Google API 客户端库:
composer require google/apiclient:^2.10
Python
如需运行本文档中的 Python 代码示例,您需要:
- Python 2.6 或更高版本
- pip 软件包管理工具。
- Python 版 Google API 客户端库:
pip install --upgrade google-api-python-client
google-auth
、google-auth-oauthlib
和google-auth-httplib2
- 用于用户授权。pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
- Flask Python Web 应用框架。
pip install --upgrade flask
requests
HTTP 库。pip install --upgrade requests
Ruby
如需运行本文档中的 Ruby 代码示例,您需要:
- Ruby 2.6 或更高版本
-
Ruby 版 Google Auth 库:
gem install googleauth
-
Sinatra Ruby Web 应用框架。
gem install sinatra
Node.js
如需运行本文档中的 Node.js 代码示例,您需要:
- 维护版 LTS、活跃 LTS 或 Node.js 当前版本。
-
Google API Node.js 客户端:
npm install googleapis crypto express express-session
HTTP/REST
您无需安装任何库,即可直接调用 OAuth 2.0 端点。
获取 OAuth 2.0 访问令牌
以下步骤展示了您的应用如何与 Google 的 OAuth 2.0 服务器进行交互,以征得用户同意以代表用户执行 API 请求。您的应用必须征得用户同意,才能执行需要用户授权的 Google API 请求。
下面的列表快速总结了这些步骤:
- 您的应用确定其所需的权限。
- 您的应用会将用户连同所请求权限的列表一起重定向到 Google。
- 用户决定是否向您的应用授予权限。
- 应用了解用户的决定。
- 如果用户授予了所请求的权限,您的应用会检索代表用户发出 API 请求所需的令牌。
第 1 步:设置授权参数
第一步是创建授权请求。该请求会设置参数来标识您的应用,并定义用户需要向您的应用授予的权限。
- 如果您使用 Google 客户端库进行 OAuth 2.0 身份验证和授权,则需要创建并配置一个对象来定义这些参数。
- 如果您直接调用 Google OAuth 2.0 端点,则会生成一个网址,并设置该网址的参数。
以下标签定义了 Web 服务器应用支持的授权参数。特定语言的示例还展示了如何使用客户端库或授权库来配置用于设置这些参数的对象。
PHP
以下代码段会创建一个 Google\Client()
对象,该对象用于定义授权请求中的参数。
该对象使用 client_secret.json 文件中的信息来标识您的应用。(如需详细了解该文件,请参阅创建授权凭据。)该对象还会标识您的应用请求访问的权限的范围,以及应用的身份验证端点的网址,该端点将处理来自 Google 的 OAuth 2.0 服务器的响应。最后,该代码会设置可选的 access_type
和 include_granted_scopes
参数。
例如,以下代码请求离线访问以管理用户的 YouTube 帐号:
$client = new Google\Client(); // Required, call the setAuthConfig function to load authorization credentials from // client_secret.json file. $client->setAuthConfig('client_secret.json'); // Required, to set the scope value, call the addScope function $client->addScope(GOOGLE_SERVICE_YOUTUBE::YOUTUBE_FORCE_SSL); // Required, call the setRedirectUri function to specify a valid redirect URI for the // provided client_id $client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'); // Recommended, offline access will give you both an access and refresh token so that // your app can refresh the access token without user interaction. $client->setAccessType('offline'); // Recommended, call the setState function. Using a state value can increase your assurance that // an incoming connection is the result of an authentication request. $client->setState($sample_passthrough_value); // Optional, if your application knows which user is trying to authenticate, it can use this // parameter to provide a hint to the Google Authentication Server. $client->setLoginHint('hint@example.com'); // Optional, call the setPrompt function to set "consent" will prompt the user for consent $client->setPrompt('consent'); // Optional, call the setIncludeGrantedScopes function with true to enable incremental // authorization $client->setIncludeGrantedScopes(true);
Python
以下代码段使用 google-auth-oauthlib.flow
模块构建授权请求。
此代码会构建一个 Flow
对象,该对象使用创建授权凭据后下载的 client_secret.json 文件中的信息标识您的应用。该对象还会标识您的应用请求访问的范围,以及应用的身份验证端点的网址,该端点将处理来自 Google 的 OAuth 2.0 服务器的响应。最后,该代码会设置可选的 access_type
和 include_granted_scopes
参数。
例如,以下代码请求离线访问以管理用户的 YouTube 帐号:
import google.oauth2.credentials import google_auth_oauthlib.flow # Required, call the from_client_secrets_file method to retrieve the client ID from a # client_secret.json file. The client ID (from that file) and access scopes are required. (You can # also use the from_client_config method, which passes the client configuration as it originally # appeared in a client secrets file but doesn't access the file itself.) flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/youtube.force-ssl']) # Required, indicate where the API server will redirect the user after the user completes # the authorization flow. The redirect URI is required. The value must exactly # match one of the authorized redirect URIs for the OAuth 2.0 client, which you # configured in the API Console. If this value doesn't match an authorized URI, # you will get a 'redirect_uri_mismatch' error. flow.redirect_uri = 'https://www.example.com/oauth2callback' # Generate URL for request to Google's OAuth 2.0 server. # Use kwargs to set optional request parameters. authorization_url, state = flow.authorization_url( # Recommended, enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Optional, enable incremental authorization. Recommended as a best practice. include_granted_scopes='true', # Optional, if your application knows which user is trying to authenticate, it can use this # parameter to provide a hint to the Google Authentication Server. login_hint='hint@example.com', # Optional, set prompt to 'consent' will prompt the user for consent prompt='consent')
Ruby
使用您创建的 client_secrets.json 文件在您的应用中配置客户端对象。配置客户端对象时,您需要指定应用需要访问的范围,以及应用身份验证端点的网址,该端点将处理来自 OAuth 2.0 服务器的响应。
例如,以下代码请求离线访问以管理用户的 YouTube 帐号:
require 'google/apis/youtube_v3' require "googleauth" require 'googleauth/stores/redis_token_store' client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json') scope = 'https://www.googleapis.com/auth/youtube.force-ssl' token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new) authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope, token_store, '/oauth2callback')
您的应用使用客户端对象执行 OAuth 2.0 操作,例如生成授权请求网址以及将访问令牌应用于 HTTP 请求。
Node.js
以下代码段会创建一个 google.auth.OAuth2
对象,该对象用于定义授权请求中的参数。
该对象使用 client_secret.json 文件中的信息来标识您的应用。如需向用户请求权限以检索访问令牌,请将用户重定向到同意页面。如需创建意见征求页面网址,请执行以下操作:
const {google} = require('googleapis'); const crypto = require('crypto'); const express = require('express'); const session = require('express-session'); /** * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI * from the client_secret.json file. To get these credentials for your application, visit * https://console.cloud.google.com/apis/credentials. */ const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for read-only Drive activity. const scopes = [ 'https://www.googleapis.com/auth/drive.metadata.readonly' ]; // Generate a secure random state value. const state = crypto.randomBytes(32).toString('hex'); // Store state in the session req.session.state = state; // Generate a url that asks permissions for the Drive activity scope const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true, // Include the state parameter to reduce the risk of CSRF attacks. state: state });
重要提示 - 只有在第一次授权时才会返回 refresh_token
。如需了解详情,请点击
此处。
HTTP/REST
Google 的 OAuth 2.0 端点位于 https://accounts.google.com/o/oauth2/v2/auth
。此端点只能通过 HTTPS 访问。普通 HTTP 连接会被拒绝。
对于 Web 服务器应用,Google 授权服务器支持以下查询字符串参数:
参数 | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
必需
您的应用的客户端 ID。您可以在 API Console Credentials page中找到此值。 |
||||||||||||||||
redirect_uri |
必需
确定在用户完成授权流程后 API 服务器会将用户重定向到何处。该值必须与您在客户端的 API Console
Credentials page中配置的 OAuth 2.0 客户端的某个已授权重定向 URI 完全匹配。如果此值与提供的 请注意, |
||||||||||||||||
response_type |
必需
确定 Google OAuth 2.0 端点是否会返回授权代码。 对于 Web 服务器应用,请将参数值设置为 |
||||||||||||||||
scope |
必需
用空格分隔的范围列表,用于标识您的应用可以代表用户访问的资源。这些值会告知 Google 向用户显示的同意屏幕。 范围可让您的应用仅请求访问所需的资源,同时还使用户能够控制他们向您的应用授予的访问权限大小。因此,请求的范围数量与征得用户同意的可能性之间存在反向关系。 YouTube Data API v3 使用以下范围:
OAuth 2.0 API 范围文档提供了可用于访问 Google API 的范围的完整列表。 我们建议您的应用尽可能在上下文中请求访问授权范围。通过增量授权,您可以在用户执行相关操作时请求其访问用户数据,这有助于您更好地了解您的应用为何需要其所请求的访问权限。 |
||||||||||||||||
access_type |
建议
指示当用户未在浏览器中使用时,您的应用是否可以刷新访问令牌。有效参数值包括 如果您的应用需要在用户不在浏览器时刷新访问令牌,请将值设置为 |
||||||||||||||||
state |
建议
指定您的应用用来维护授权请求和授权服务器响应之间的状态的任何字符串值。在用户同意或拒绝应用的访问请求后,服务器会返回您在 您可以将此参数用于多种用途,例如将用户定向到应用中的正确资源、发送 Nonce,以及减少跨站请求伪造问题。由于您的 |
||||||||||||||||
include_granted_scopes |
可选
允许应用使用增量授权在上下文中请求访问其他范围。如果您将此参数的值设为 |
||||||||||||||||
enable_granular_consent |
可选
默认为 当 Google 为应用启用精细权限后,此参数将不再有任何影响。 |
||||||||||||||||
login_hint |
可选
如果您的应用知道哪个用户正在尝试进行身份验证,它可以使用此参数向 Google Authentication 服务器提供提示。服务器会根据该提示,通过在登录表单中预填充电子邮件字段或选择适当的多登录会话来简化登录流程。 将该参数值设为电子邮件地址或 |
||||||||||||||||
prompt |
可选
向用户显示的提示列表,以空格分隔(区分大小写)。如果您未指定此参数,则系统只会在项目首次请求访问权限时提示用户。如需了解详情,请参阅 提示重新征得用户同意。 可能的值包括:
|
第 2 步:重定向到 Google 的 OAuth 2.0 服务器
将用户重定向到 Google 的 OAuth 2.0 服务器,以启动身份验证和授权流程。通常,当应用首次需要访问用户的数据时,就会发生这种情况。对于增量授权,当您的应用首次需要访问其无权访问的其他资源时,也会执行此步骤。
PHP
- 生成一个网址,以请求 Google 的 OAuth 2.0 服务器的访问权限:
$auth_url = $client->createAuthUrl();
- 将用户重定向到
$auth_url
:header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
Python
以下示例展示了如何使用 Flask Web 应用框架将用户重定向到授权网址:
return flask.redirect(authorization_url)
Ruby
- 生成一个网址,以请求 Google 的 OAuth 2.0 服务器的访问权限:
auth_uri = authorizer.get_authorization_url(login_hint: user_id, request: request)
- 将用户重定向到
auth_uri
。
Node.js
-
使用第 1 步中生成的网址
authorizationUrl
generateAuthUrl
方法向 Google 的 OAuth 2.0 服务器请求访问权限。 -
将用户重定向到
authorizationUrl
。res.redirect(authorizationUrl);
HTTP/REST
Sample redirect to Google's authorization server
The sample URL below requests offline access
(access_type=offline
) to a scope that permits access to view
the user's YouTube account. It uses incremental authorization to ensure that
the new access token covers any scopes to which the user previously granted
the application access. The URL also sets values for the required
redirect_uri
, response_type
, and
client_id
parameters as well as for the state
parameter. The URL contains line breaks and spaces for readability.
https://accounts.google.com/o/oauth2/v2/auth?
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
access_type=offline&
include_granted_scopes=true&
state=state_parameter_passthrough_value&
redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
response_type=code&
client_id=client_id
创建请求网址后,将用户重定向到该网址。
Google 的 OAuth 2.0 服务器会验证用户身份,并请求用户同意您的应用访问所请求的范围。系统将使用您指定的重定向网址将响应发送回您的应用。
第 3 步:Google 提示用户同意
在此步骤中,用户会决定是否授予您的应用请求的访问权限。在这一阶段,Google 会显示一个同意窗口,其中显示应用的名称以及它请求通过用户授权凭据访问的 Google API 服务,以及要授予的访问权限范围的摘要。然后,用户可以同意授予对您的应用请求的一个或多个范围的访问权限,或拒绝请求。
在此阶段,您的应用无需执行任何操作,因为它需要等待 Google 的 OAuth 2.0 服务器做出响应(表明是否已授予任何访问权限)。以下步骤介绍了该响应。
错误
向 Google 的 OAuth 2.0 授权端点发送请求时,系统可能会显示面向用户的错误消息,而不是预期的身份验证和授权流程。下面列出了常见的错误代码和建议的解决方案。
admin_policy_enforced
由于 Google Workspace 管理员的政策,Google 账号无法向所请求的一个或多个范围授权。请参阅 Google Workspace 管理员帮助文章 控制哪些第三方应用和内部应用可以访问 Google Workspace 数据,详细了解管理员如何限制对所有范围或敏感范围和受限范围的访问权限,直到明确向您的 OAuth 客户端 ID 授予访问权限为止。
disallowed_useragent
授权端点显示在 Google 的 OAuth 2.0 政策禁止的嵌入式用户代理内。
Android
Android 开发者在 android.webkit.WebView
中打开授权请求时可能会遇到此错误消息。开发者应改用 Android 库,例如 Google 登录(适用于 Android)或 OpenID Foundation 的 AppAuth for Android。
当 Android 应用在嵌入式用户代理中打开常规网页链接,并且用户从您的网站转到 Google 的 OAuth 2.0 授权端点时,Web 开发者可能会遇到此错误。开发者应允许在操作系统的默认链接处理程序(包括 Android App Links 处理程序或默认浏览器应用)中打开常规链接。Android 自定义标签页库也是一个受支持的选项。
iOS
iOS 和 macOS 开发者在 WKWebView
中打开授权请求时可能会遇到此错误。
开发者应改用 iOS 库,例如 Google 登录适用于 iOS 或 OpenID Foundation 的 AppAuth for iOS。
当 iOS 或 macOS 应用在嵌入式用户代理中打开常规 Web 链接,并且用户从您的网站转到 Google 的 OAuth 2.0 授权端点时,Web 开发者可能会遇到此错误。开发者应允许在操作系统的默认链接处理程序中打开常规链接,该操作系统包含通用链接处理程序或默认浏览器应用。SFSafariViewController
库也是一个受支持的选项。
org_internal
请求中的 OAuth 客户端 ID 属于限制对特定 Google Cloud 组织中的 Google 账号的访问权限的项目的一部分。如需详细了解此配置选项,请参阅“设置 OAuth 同意屏幕”帮助文章中的用户类型部分。
invalid_client
OAuth 客户端密钥不正确。查看 OAuth 客户端配置,包括用于此请求的客户端 ID 和密钥。
invalid_grant
刷新访问令牌或使用增量授权时,令牌可能已过期或已失效。再次对用户进行身份验证,并请求用户同意以获取新令牌。如果您仍然看到此错误消息,请确保您的应用已正确配置,并且您在请求中使用的令牌和参数正确无误。否则,用户帐号可能已被删除或停用。
redirect_uri_mismatch
授权请求中传递的 redirect_uri
与 OAuth 客户端 ID 的授权重定向 URI 不匹配。在 Google API Console Credentials page中查看已获授权的重定向 URI。
redirect_uri
参数可能是指已弃用且不再受支持的 OAuth 带外 (OOB) 流程。如需更新您的集成,请参阅迁移指南。
invalid_request
您提出的请求存在问题。这可能是由于多种原因造成的:
- 该请求的格式不正确
- 该请求缺少必需参数
- 请求使用了 Google 不支持的授权方法。验证您的 OAuth 集成是否使用了推荐的集成方法
第 4 步:处理 OAuth 2.0 服务器响应
OAuth 2.0 服务器使用请求中指定的网址来响应您应用的访问请求。
如果用户批准了访问请求,响应中就会包含授权代码。如果用户未批准请求,响应将包含错误消息。返回给网络服务器的授权代码或错误消息会显示在查询字符串中,如下所示:
错误响应:
https://oauth2.example.com/auth?error=access_denied
授权代码响应:
https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7
OAuth 2.0 服务器响应示例
您可以通过点击以下示例网址来测试此流程,该网址请求获取对您 Google 云端硬盘中的文件对应的元数据的只读权限:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly& access_type=offline& include_granted_scopes=true& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& response_type=code& client_id=client_id
完成 OAuth 2.0 流程后,您应该会被重定向到 http://localhost/oauth2callback
。除非您的本地机器在该地址传送文件,否则它可能会生成 404 NOT FOUND
错误。下一步会更详细地介绍当用户被重定向回您的应用时,URI 中返回的信息。
第 5 步:用授权代码来刷新和访问令牌
网络服务器收到授权代码后,可以使用授权代码换取访问令牌。
PHP
要使用授权代码换取访问令牌,请使用 authenticate
方法:
$client->authenticate($_GET['code']);
您可以使用 getAccessToken
方法检索访问令牌:
$access_token = $client->getAccessToken();
Python
在您的回调页面上,使用 google-auth
库验证授权服务器响应。然后,使用 flow.fetch_token
方法将该响应中的授权代码交换为访问令牌:
state = flask.session['state'] flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/youtube.force-ssl'], state=state) flow.redirect_uri = flask.url_for('oauth2callback', _external=True) authorization_response = flask.request.url flow.fetch_token(authorization_response=authorization_response) # Store the credentials in the session. # ACTION ITEM for developers: # Store user's access and refresh tokens in your data store if # incorporating this code into your real app. credentials = flow.credentials flask.session['credentials'] = { 'token': credentials.token, 'refresh_token': credentials.refresh_token, 'token_uri': credentials.token_uri, 'client_id': credentials.client_id, 'client_secret': credentials.client_secret, 'scopes': credentials.scopes}
Ruby
在您的回调页面上,使用 googleauth
库验证授权服务器响应。使用 authorizer.handle_auth_callback_deferred
方法保存授权代码并重定向回最初请求授权的网址。该操作通过将结果暂时存储在用户的会话中,来推迟代码的交换。
target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request) redirect target_url
Node.js
要使用授权代码换取访问令牌,请使用 getToken
方法:
const url = require('url'); // Receive the callback from Google's OAuth 2.0 server. app.get('/oauth2callback', async (req, res) => { let q = url.parse(req.url, true).query; if (q.error) { // An error response e.g. error=access_denied console.log('Error:' + q.error); } else if (q.state !== req.session.state) { //check state value console.log('State mismatch. Possible CSRF attack'); res.end('State mismatch. Possible CSRF attack'); } else { // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); oauth2Client.setCredentials(tokens); });
HTTP/REST
如需使用授权代码换取访问令牌,请调用 https://oauth2.googleapis.com/token
端点并设置以下参数:
字段 | |
---|---|
client_id |
从 Credentials page中获取的客户端 ID。 API Console |
client_secret |
从 Credentials page中获取的客户端密钥。 API Console |
code |
初始请求返回的授权代码。 |
grant_type |
根据 OAuth 2.0 规范中的定义,此字段的值必须设置为 authorization_code 。 |
redirect_uri |
在给定 client_id 的 API Console
Credentials page 中,为您的项目列出的某个重定向 URI。 |
以下代码段展示了一个示例请求:
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
Google 通过返回一个 JSON 对象来响应此请求,该对象包含短期有效的访问令牌和刷新令牌。请注意,只有当您的应用在向 Google 授权服务器发出的初始请求中将 access_type
参数设置为 offline
时,系统才会返回刷新令牌。
响应包含以下字段:
字段 | |
---|---|
access_token |
您的应用发送的令牌,用于向 Google API 请求授权。 |
expires_in |
访问令牌的剩余生命周期(以秒为单位)。 |
refresh_token |
可用于获取新访问令牌的令牌。刷新令牌在用户撤消访问权限之前一直有效。同样,只有当您在向 Google 授权服务器发出的初始请求中将 access_type 参数设为 offline 时,此字段才会显示在此响应中。
|
scope |
access_token 授予的访问权限范围,表示为以空格分隔、区分大小写的字符串列表。 |
token_type |
返回的令牌的类型。此时,此字段的值始终设置为 Bearer 。 |
以下代码段展示了一个示例响应:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
错误
用授权代码换取访问令牌时,您可能会遇到以下错误(而非预期响应)。下面列出了常见的错误代码和建议的解决方案。
invalid_grant
提供的授权代码无效或格式不正确。通过重新启动 OAuth 流程来请求新代码,以再次提示用户同意。
调用 Google API
PHP
完成以下步骤,以使用访问令牌调用 Google API:
- 如果您需要将访问令牌应用于新的
Google\Client
对象(例如,如果您将访问令牌存储在用户会话中),请使用setAccessToken
方法:$client->setAccessToken($access_token);
- 为您要调用的 API 构建服务对象。如需构建服务对象,您可以向要调用的 API 的构造函数提供已获授权的
Google\Client
对象。例如,如需调用 YouTube Data API,请使用以下代码:$youtube = new Google_Service_YouTube($client);
- 使用服务对象提供的接口向 API 服务发出请求。例如,如需检索有关已获授权的用户的 YouTube 频道的数据,请使用以下代码:
$channel = $youtube->channels->listChannels('snippet', array('mine' => $mine));
Python
获得访问令牌后,您的应用可以使用该令牌代表给定用户帐号或服务帐号授权 API 请求。使用特定于用户的授权凭据为您要调用的 API 构建服务对象,然后使用该对象发出已获授权的 API 请求。
- 为您要调用的 API 构建服务对象。如需构建服务对象,您可以使用 API 的名称、版本以及用户凭据来调用
googleapiclient.discovery
库的build
方法: 例如,调用 YouTube Data API 版本 3:from googleapiclient.discovery import build youtube = build('youtube', 'v3', credentials=credentials)
- 使用服务对象提供的接口向 API 服务发出请求。例如,如需检索有关已获授权的用户的 YouTube 频道的数据,请使用以下代码:
channel = youtube.channels().list(mine=True, part='snippet').execute()
Ruby
获得访问令牌后,您的应用可以使用该令牌代表给定的用户帐号或服务帐号发出 API 请求。使用特定于用户的授权凭据为您要调用的 API 构建服务对象,然后使用该对象发出已获授权的 API 请求。
- 为您要调用的 API 构建服务对象。
例如,如需调用 YouTube Data API 版本 3,请使用以下代码:
youtube = Google::Apis::YoutubeV3::YouTubeService.new
- 在服务上设置凭据:
youtube.authorization = credentials
- 使用服务对象提供的接口向 API 服务发出请求。例如,如需检索有关授权用户的 YouTube 频道的数据,请使用以下表达式:
channel = youtube.list_channels(part, :mine => mine)
或者,可以通过向某个方法提供 options
参数,按方法提供授权:
channel = youtube.list_channels(part, :mine => mine, options: { authorization: auth_client })
Node.js
获取访问令牌并将其设置为 OAuth2
对象后,使用该对象调用 Google API。您的应用可以使用该令牌代表给定用户帐号或服务帐号向 API 请求授权。为您要调用的 API 构建服务对象。
const { google } = require('googleapis'); // Example of using Google Drive API to list filenames in user's Drive. const drive = google.drive('v3'); drive.files.list({ auth: oauth2Client, pageSize: 10, fields: 'nextPageToken, files(id, name)', }, (err1, res1) => { if (err1) return console.log('The API returned an error: ' + err1); const files = res1.data.files; if (files.length) { console.log('Files:'); files.map((file) => { console.log(`${file.name} (${file.id})`); }); } else { console.log('No files found.'); } });
HTTP/REST
在您的应用获得访问令牌后,如果已授予 Google API 所需的访问权限范围,您就可以使用令牌代表指定用户账号调用该 API。为此,请通过加入 access_token
查询参数或 Authorization
HTTP 标头 Bearer
值,将访问令牌添加到对 API 的请求中。请尽可能使用 HTTP 标头,因为查询字符串往往会显示在服务器日志中。在大多数情况下,您可以使用客户端库来设置对 Google API 的调用(例如,调用 YouTube Data API 时)。
请注意,YouTube Data API 仅支持拥有并管理多个 YouTube 频道的 YouTube 内容所有者(例如唱片公司和电影制片公司)的服务帐号。
您可以在 OAuth 2.0 Playground 中试用所有 Google API 并查看其范围。
HTTP GET 示例
使用 Authorization: Bearer
HTTP 标头对
youtube.channels
端点 (YouTube Data API) 的调用可能如下所示。请注意,您需要指定自己的访问令牌:
GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
以下是使用 access_token
查询字符串参数对已通过身份验证的用户的同一 API 的调用:
GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
curl
个示例
您可以使用 curl
命令行应用测试这些命令。以下是使用 HTTP 标头选项(首选)的示例:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true
或者,也可以使用查询字符串参数选项:
curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
完整示例
以下示例会输出一个 JSON 格式的对象,该对象会在用户进行身份验证并授权应用管理用户的 YouTube 帐号后,显示其 YouTube 频道的相关信息。
PHP
如需运行此示例,请执行以下操作:
- 在 API Console中,将本地机器的网址添加到重定向网址列表中。例如,添加
http://localhost:8080
。 - 创建一个新目录并切换到该目录。例如:
mkdir ~/php-oauth2-example cd ~/php-oauth2-example
- 使用 Composer 安装适用于 PHP 的 Google API 客户端库:
composer require google/apiclient:^2.10
- 使用以下内容创建
index.php
和oauth2callback.php
文件。 - 使用配置为提供 PHP 的 Web 服务器运行该示例。如果您使用的是 PHP 5.6 或更高版本,则可以使用 PHP 的内置测试网络服务器:
php -S localhost:8080 ~/php-oauth2-example
index.php
<?php require_once __DIR__.'/vendor/autoload.php'; session_start(); $client = new Google\Client(); $client->setAuthConfig('client_secrets.json'); $client->addScope(GOOGLE_SERVICE_YOUTUBE::YOUTUBE_FORCE_SSL); if (isset($_SESSION['access_token']) && $_SESSION['access_token']) { $client->setAccessToken($_SESSION['access_token']); $youtube = new Google_Service_YouTube($client); $channel = $youtube->channels->listChannels('snippet', array('mine' => $mine)); echo json_encode($channel); } else { $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'; header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL)); }
oauth2callback.php
<?php require_once __DIR__.'/vendor/autoload.php'; session_start(); $client = new Google\Client(); $client->setAuthConfigFile('client_secrets.json'); $client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'); $client->addScope(GOOGLE_SERVICE_YOUTUBE::YOUTUBE_FORCE_SSL); if (! isset($_GET['code'])) { // Generate and set state value $state = bin2hex(random_bytes(16)); $client->setState($state); $_SESSION['state'] = $state; $auth_url = $client->createAuthUrl(); header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL)); } else { // Check the state value if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['state']) { die('State mismatch. Possible CSRF attack.'); } $client->authenticate($_GET['code']); $_SESSION['access_token'] = $client->getAccessToken(); $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/'; header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL)); }
Python
此示例使用 Flask 框架。它在 http://localhost:8080
上运行一个 Web 应用,可让您测试 OAuth 2.0 流程。如果您转到该网址,应该会看到四个链接:
- 测试 API 请求:此链接指向尝试执行示例 API 请求的网页。如有必要,它会启动授权流程。如果成功,页面会显示 API 响应。
- 直接测试身份验证流程:此链接指向尝试通过授权流程发送用户的页面。应用请求权限,以代表用户提交已获授权的 API 请求。
- 撤消当前凭据:此链接指向的页面会 撤消用户已向应用授予的权限。
- 清除 Flask 会话凭据:此链接会清除存储在 Flask 会话中的授权凭据。这样,您就可以了解如果已经向您的应用授予权限的用户尝试在新会话中执行 API 请求,会发生什么情况。此外,您还可以利用它查看,如果用户撤消了向您的应用授予的权限,而您的应用仍尝试使用撤消的访问令牌向请求授权,该应用将会收到 API 响应。
# -*- coding: utf-8 -*- import os import flask import requests import google.oauth2.credentials import google_auth_oauthlib.flow import googleapiclient.discovery # This variable specifies the name of a file that contains the OAuth 2.0 # information for this application, including its client_id and client_secret. CLIENT_SECRETS_FILE = "client_secret.json" # This OAuth 2.0 access scope allows for full read/write access to the # authenticated user's account and requires requests to use an SSL connection. SCOPES = ['https://www.googleapis.com/auth/youtube.force-ssl'] API_SERVICE_NAME = 'youtube' API_VERSION = 'v3' app = flask.Flask(__name__) # Note: A secret key is included in the sample so that it works. # If you use this code in your application, replace this with a truly secret # key. See https://flask.palletsprojects.com/quickstart/#sessions. app.secret_key = 'REPLACE ME - this value is here as a placeholder.' @app.route('/') def index(): return print_index_table() @app.route('/test') def test_api_request(): if 'credentials' not in flask.session: return flask.redirect('authorize') # Load credentials from the session. credentials = google.oauth2.credentials.Credentials( **flask.session['credentials']) youtube = googleapiclient.discovery.build( API_SERVICE_NAME, API_VERSION, credentials=credentials) channel = youtube.channels().list(mine=True, part='snippet').execute() # Save credentials back to session in case access token was refreshed. # ACTION ITEM: In a production app, you likely want to save these # credentials in a persistent database instead. flask.session['credentials'] = credentials_to_dict(credentials) return flask.jsonify(**channel) @app.route('/authorize') def authorize(): # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps. flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( CLIENT_SECRETS_FILE, scopes=SCOPES) # The URI created here must exactly match one of the authorized redirect URIs # for the OAuth 2.0 client, which you configured in the API Console. If this # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch' # error. flow.redirect_uri = flask.url_for('oauth2callback', _external=True) authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true') # Store the state so the callback can verify the auth server response. flask.session['state'] = state return flask.redirect(authorization_url) @app.route('/oauth2callback') def oauth2callback(): # Specify the state when creating the flow in the callback so that it can # verified in the authorization server response. state = flask.session['state'] flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( CLIENT_SECRETS_FILE, scopes=SCOPES, state=state) flow.redirect_uri = flask.url_for('oauth2callback', _external=True) # Use the authorization server's response to fetch the OAuth 2.0 tokens. authorization_response = flask.request.url flow.fetch_token(authorization_response=authorization_response) # Store credentials in the session. # ACTION ITEM: In a production app, you likely want to save these # credentials in a persistent database instead. credentials = flow.credentials flask.session['credentials'] = credentials_to_dict(credentials) return flask.redirect(flask.url_for('test_api_request')) @app.route('/revoke') def revoke(): if 'credentials' not in flask.session: return ('You need to <a href="/authorize">authorize</a> before ' + 'testing the code to revoke credentials.') credentials = google.oauth2.credentials.Credentials( **flask.session['credentials']) revoke = requests.post('https://oauth2.googleapis.com/revoke', params={'token': credentials.token}, headers = {'content-type': 'application/x-www-form-urlencoded'}) status_code = getattr(revoke, 'status_code') if status_code == 200: return('Credentials successfully revoked.' + print_index_table()) else: return('An error occurred.' + print_index_table()) @app.route('/clear') def clear_credentials(): if 'credentials' in flask.session: del flask.session['credentials'] return ('Credentials have been cleared.<br><br>' + print_index_table()) def credentials_to_dict(credentials): return {'token': credentials.token, 'refresh_token': credentials.refresh_token, 'token_uri': credentials.token_uri, 'client_id': credentials.client_id, 'client_secret': credentials.client_secret, 'scopes': credentials.scopes} def print_index_table(): return ('<table>' + '<tr><td><a href="/test">Test an API request</a></td>' + '<td>Submit an API request and see a formatted JSON response. ' + ' Go through the authorization flow if there are no stored ' + ' credentials for the user.</td></tr>' + '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' + '<td>Go directly to the authorization flow. If there are stored ' + ' credentials, you still might not be prompted to reauthorize ' + ' the application.</td></tr>' + '<tr><td><a href="/revoke">Revoke current credentials</a></td>' + '<td>Revoke the access token associated with the current user ' + ' session. After revoking credentials, if you go to the test ' + ' page, you should see an <code>invalid_grant</code> error.' + '</td></tr>' + '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' + '<td>Clear the access token currently stored in the user session. ' + ' After clearing the token, if you <a href="/test">test the ' + ' API request</a> again, you should go back to the auth flow.' + '</td></tr></table>') if __name__ == '__main__': # When running locally, disable OAuthlib's HTTPs verification. # ACTION ITEM for developers: # When running in production *do not* leave this option enabled. os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' # Specify a hostname and port that are set as a valid redirect URI # for your API project in the Google API Console. app.run('localhost', 8080, debug=True)
Ruby
此示例使用 Sinatra 框架。
require 'google/apis/youtube_v3' require 'sinatra' require 'googleauth' require 'googleauth/stores/redis_token_store' configure do enable :sessions set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json') set :scope, Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new) set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope, settings.token_store, '/oauth2callback') end get '/' do user_id = settings.client_id.id credentials = settings.authorizer.get_credentials(user_id, request) if credentials.nil? redirect settings.authorizer.get_authorization_url(login_hint: user_id, request: request) end youtube = Google::Apis::YoutubeV3::YouTubeService.new channel = youtube.list_channels(part, :mine => mine, options: { authorization: auth_client }) "<pre>#{JSON.pretty_generate(channel.to_h)}</pre>" end get '/oauth2callback' do target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request) redirect target_url end
Node.js
如需运行此示例,请执行以下操作:
-
在 API Console中,将本地机器的网址添加到重定向网址列表中。例如,添加
http://localhost
。 - 确保您已安装维护 LTS、活跃 LTS 或 Node.js 的当前版本。
-
创建一个新目录并切换到该目录。例如:
mkdir ~/nodejs-oauth2-example cd ~/nodejs-oauth2-example
-
Install the
Google API Client
Library
for Node.js using npm:
npm install googleapis
-
使用以下内容创建
main.js
文件。 -
运行示例:
node .\main.js
main.js
const http = require('http'); const https = require('https'); const url = require('url'); const { google } = require('googleapis'); const crypto = require('crypto'); const express = require('express'); const session = require('express-session'); /** * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI. * To get these credentials for your application, visit * https://console.cloud.google.com/apis/credentials. */ const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for read-only Drive activity. const scopes = [ 'https://www.googleapis.com/auth/drive.metadata.readonly' ]; /* Global variable that stores user credential in this code example. * ACTION ITEM for developers: * Store user's refresh token in your data store if * incorporating this code into your real app. * For more information on handling refresh tokens, * see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens */ let userCredential = null; async function main() { const app = express(); app.use(session({ secret: 'your_secure_secret_key', // Replace with a strong secret resave: false, saveUninitialized: false, })); // Example on redirecting user to Google's OAuth 2.0 server. app.get('/', async (req, res) => { // Generate a secure random state value. const state = crypto.randomBytes(32).toString('hex'); // Store state in the session req.session.state = state; // Generate a url that asks permissions for the Drive activity scope const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true, // Include the state parameter to reduce the risk of CSRF attacks. state: state }); res.redirect(authorizationUrl); }); // Receive the callback from Google's OAuth 2.0 server. app.get('/oauth2callback', async (req, res) => { // Handle the OAuth 2.0 server response let q = url.parse(req.url, true).query; if (q.error) { // An error response e.g. error=access_denied console.log('Error:' + q.error); } else if (q.state !== req.session.state) { //check state value console.log('State mismatch. Possible CSRF attack'); res.end('State mismatch. Possible CSRF attack'); } else { // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); oauth2Client.setCredentials(tokens); /** Save credential to the global variable in case access token was refreshed. * ACTION ITEM: In a production app, you likely want to save the refresh token * in a secure persistent database instead. */ userCredential = tokens; // Example of using Google Drive API to list filenames in user's Drive. const drive = google.drive('v3'); drive.files.list({ auth: oauth2Client, pageSize: 10, fields: 'nextPageToken, files(id, name)', }, (err1, res1) => { if (err1) return console.log('The API returned an error: ' + err1); const files = res1.data.files; if (files.length) { console.log('Files:'); files.map((file) => { console.log(`${file.name} (${file.id})`); }); } else { console.log('No files found.'); } }); } }); // Example on revoking a token app.get('/revoke', async (req, res) => { // Build the string for the POST request let postData = "token=" + userCredential.access_token; // Options for POST request to Google's OAuth 2.0 server to revoke a token let postOptions = { host: 'oauth2.googleapis.com', port: '443', path: '/revoke', method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Content-Length': Buffer.byteLength(postData) } }; // Set up the request const postReq = https.request(postOptions, function (res) { res.setEncoding('utf8'); res.on('data', d => { console.log('Response: ' + d); }); }); postReq.on('error', error => { console.log(error) }); // Post the request with data postReq.write(postData); postReq.end(); }); const server = http.createServer(app); server.listen(80); } main().catch(console.error);
HTTP/REST
此 Python 示例使用 Flask 框架和 Requests 库演示 OAuth 2.0 Web 流程。我们建议为此流程使用 Python 版 Google API 客户端库。(Python 标签页中的示例确实使用了客户端库。)
import json import flask import requests app = flask.Flask(__name__) CLIENT_ID = '123456789.apps.googleusercontent.com' CLIENT_SECRET = 'abc123' # Read from a file or environmental variable in a real app SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl' REDIRECT_URI = 'http://example.com/oauth2callback' @app.route('/') def index(): if 'credentials' not in flask.session: return flask.redirect(flask.url_for('oauth2callback')) credentials = json.loads(flask.session['credentials']) if credentials['expires_in'] <= 0: return flask.redirect(flask.url_for('oauth2callback')) else: headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])} req_uri = 'https://www.googleapis.com/youtube/v3/channels/list' r = requests.get(req_uri, headers=headers) return r.text @app.route('/oauth2callback') def oauth2callback(): if 'code' not in flask.request.args: state = str(uuid.uuid4()) flask.session['state'] = state auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code' '&client_id={}&redirect_uri={}&scope={}&state={}').format(CLIENT_ID, REDIRECT_URI, SCOPE, state) return flask.redirect(auth_uri) else: if 'state' not in flask.request.args or flask.request.args['state'] != flask.session['state']: return 'State mismatch. Possible CSRF attack.', 400 auth_code = flask.request.args.get('code') data = {'code': auth_code, 'client_id': CLIENT_ID, 'client_secret': CLIENT_SECRET, 'redirect_uri': REDIRECT_URI, 'grant_type': 'authorization_code'} r = requests.post('https://oauth2.googleapis.com/token', data=data) flask.session['credentials'] = r.text return flask.redirect(flask.url_for('index')) if __name__ == '__main__': import uuid app.secret_key = str(uuid.uuid4()) app.debug = False app.run()
重定向 URI 验证规则
为了帮助开发者保障其应用的安全,Google 会对重定向 URI 应用以下验证规则。您的重定向 URI 必须遵守这些规则。如需了解下文提及的域名、主机、路径、查询、架构和 userinfo 的定义,请参阅 RFC 3986 第 3 节。
验证规则 | |
---|---|
架构 |
重定向 URI 必须使用 HTTPS 架构,而非普通的 HTTP。本地主机 URI(包括 localhost IP 地址 URI)不受此规则限制。 |
主机 |
主机不能是原始 IP 地址。本地主机 IP 地址不受此规则限制。 |
网域 |
“googleusercontent.com” 。goo.gl ),除非应用拥有该网域。此外,如果拥有缩短版网域的应用选择重定向到该网域,则该重定向 URI 的路径中必须包含 “/google-callback/” ,或以 “/google-callback” 结尾。 |
用户信息 |
重定向 URI 不能包含 userinfo 子组件。 |
路径 |
重定向 URI 不能包含路径遍历(也称为目录回溯),后者以 |
查询 |
重定向 URI 不能包含开放重定向。 |
fragment |
重定向 URI 不能包含 fragment 组件。 |
字符 |
重定向 URI 不能包含某些字符,包括:
|
递增授权
在 OAuth 2.0 协议中,您的应用会请求对访问由范围标识的资源的授权。在您需要时请求对资源进行授权被认为是一种最佳用户体验做法。为了实现这种做法,Google 的授权服务器支持增量授权。此功能允许您根据需要请求范围,如果用户授予新范围的权限,则会返回授权代码,您可以使用该代码来换取包含用户已授予项目的所有范围的令牌。
例如,假设某个应用可帮助用户识别有趣的本地事件。借助该应用,用户可以观看有关这些活动的视频、为视频评分,以及将视频添加到播放列表。用户还可以使用该应用将活动添加到其 Google 日历中。
在这种情况下,在登录时,应用可能不需要或请求对任何范围的访问权限。不过,如果用户尝试对视频评分、将视频添加到播放列表或执行其他 YouTube 操作,则应用可以请求访问 https://www.googleapis.com/auth/youtube.force-ssl
范围。同样,如果用户尝试添加日历活动,则应用可能会请求访问 https://www.googleapis.com/auth/calendar
范围。
如需实现增量授权,请完成请求访问令牌的正常流程,但要确保授权请求包含之前授予的范围。此方法可让您的应用避免管理多个访问令牌。
以下规则适用于通过增量授权获取的访问令牌:
- 令牌可用于访问与整合到新的组合授权中的任何范围相对应的资源。
- 当您将刷新令牌用于合并授权以获取访问令牌时,访问令牌代表合并授权,并可用于响应中包含的任何
scope
值。 - 组合授权包括用户授予 API 项目的所有范围,即使授权是从不同的客户端请求也是如此。例如,如果用户使用应用的桌面客户端向一个范围授予访问权限,然后通过移动客户端向同一应用授予另一个范围,则合并授权将同时涵盖这两个范围。
- 如果您撤消代表合并授权的令牌,则代表关联用户对该授权范围的所有访问权限都会被同时撤消。
第 1 步:设置授权参数中特定于语言的代码示例和第 2 步:重定向到 Google 的 OAuth 2.0 服务器中的示例 HTTP/REST 重定向网址均使用增量授权。以下代码示例还显示了使用增量授权需要添加的代码。
PHP
$client->setIncludeGrantedScopes(true);
Python
在 Python 中,将 include_granted_scopes
关键字参数设置为 true
,以确保授权请求包含之前授予的范围。include_granted_scopes
很可能不是您设置的唯一关键字参数,如以下示例所示。
authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true')
Ruby
auth_client.update!( :additional_parameters => {"include_granted_scopes" => "true"} )
Node.js
const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true });
HTTP/REST
在本例中,除了用户已向应用授予的任何其他访问权限之外,发起调用的应用还会请求检索用户的 YouTube 数据分析数据的权限。
GET https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& access_type=offline& state=security_token%3D138rk%3Btarget_url%3Dhttp...index& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& response_type=code& client_id=client_id& include_granted_scopes=true
Refreshing an access token (offline access)
Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.
- If you use a Google API Client Library, the client object refreshes the access token as needed as long as you configure that object for offline access.
- If you are not using a client library, you need to set the
access_type
HTTP query parameter tooffline
when redirecting the user to Google's OAuth 2.0 server. In that case, Google's authorization server returns a refresh token when you exchange an authorization code for an access token. Then, if the access token expires (or at any other time), you can use a refresh token to obtain a new access token.
Requesting offline access is a requirement for any application that needs to access a Google
API when the user is not present. For example, an app that performs backup services or
executes actions at predetermined times needs to be able to refresh its access token when the
user is not present. The default style of access is called online
.
Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.
PHP
If your application needs offline access to a Google API, set the API client's access type to
offline
:
$client->setAccessType("offline");
在用户授予对所请求范围的离线访问权限后,您可以在用户离线时继续使用 API 客户端代表该用户访问 Google API。客户端对象会根据需要刷新访问令牌。
Python
在 Python 中,请将 access_type
关键字参数设置为 offline
,以确保能够刷新访问令牌,而无需重新提示用户授予权限。access_type
很可能不是您设置的唯一关键字参数,如以下示例所示。
authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true')
在用户授予对所请求范围的离线访问权限后,您可以在用户离线时继续使用 API 客户端代表该用户访问 Google API。客户端对象会根据需要刷新访问令牌。
Ruby
如果您的应用需要离线访问 Google API,请将 API 客户端的访问权限类型设置为 offline
:
auth_client.update!( :additional_parameters => {"access_type" => "offline"} )
在用户授予对所请求范围的离线访问权限后,您可以在用户离线时继续使用 API 客户端代表该用户访问 Google API。客户端对象会根据需要刷新访问令牌。
Node.js
如果您的应用需要离线访问 Google API,请将 API 客户端的访问权限类型设置为 offline
:
const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true });
在用户授予对所请求范围的离线访问权限后,您可以在用户离线时继续使用 API 客户端代表该用户访问 Google API。客户端对象会根据需要刷新访问令牌。
访问令牌会过期。此库将在即将过期时自动使用刷新令牌获取新的访问令牌。要确保始终存储最新令牌,一种简单的方法是使用令牌事件:
oauth2Client.on('tokens', (tokens) => { if (tokens.refresh_token) { // store the refresh_token in your secure persistent database console.log(tokens.refresh_token); } console.log(tokens.access_token); });
此令牌事件仅在第一次授权中发生,因此在调用 generateAuthUrl
方法以接收刷新令牌时,您需要将 access_type
设置为 offline
。如果您已为应用授予了必要的权限,但没有针对接收刷新令牌设置适当的约束,则需要重新授权应用接收新的刷新令牌。
如需稍后设置 refresh_token
,您可以使用 setCredentials
方法:
oauth2Client.setCredentials({ refresh_token: `STORED_REFRESH_TOKEN` });
客户端获取刷新令牌后,将在下次调用该 API 时自动获取并刷新访问令牌。
HTTP/REST
为了刷新访问令牌,您的应用会向 Google 的授权服务器 (https://oauth2.googleapis.com/token
) 发送 HTTPS POST
请求,其中包含以下参数:
字段 | |
---|---|
client_id |
从 API Console获取的客户端 ID。 |
client_secret |
从 API Console获取的客户端密钥。 |
grant_type |
根据 OAuth 2.0 规范中所定义,此字段的值必须设置为 refresh_token 。 |
refresh_token |
从授权代码交换返回的刷新令牌。 |
以下代码段展示了一个示例请求:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
只要用户未撤消授予应用的访问权限,令牌服务器就会返回一个包含新访问令牌的 JSON 对象。以下代码段显示了一个示例响应:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly", "token_type": "Bearer" }
请注意,可以发放的刷新令牌的数量是有限制的;每个客户端/用户组合一个,以及所有客户端中每位用户一个。您应将刷新令牌保存在长期存储空间中,并且只要它们保持有效状态,就应继续使用。如果您的应用请求的刷新令牌过多,可能会受到这些限制,在这种情况下,较旧的刷新令牌将会停止工作。
撤消令牌
在某些情况下,用户可能希望撤消已授予应用的访问权限。用户可以通过访问 账号设置来撤消访问权限。有关详情,请参阅有权访问您账号的第三方网站和应用中的“撤消网站或应用的访问权限”部分支持文档。
应用也可以通过编程方式撤消已向其授予的访问权限。当用户取消订阅、移除应用或应用所需的 API 资源发生显著变化时,程序化撤消会非常重要。也就是说,移除流程的一部分可以包含 API 请求,以确保移除之前向应用授予的权限。
PHP
如需以编程方式撤消令牌,请调用 revokeToken()
:
$client->revokeToken();
Python
如需以编程方式撤消令牌,请向 https://oauth2.googleapis.com/revoke
发出请求,在其中以参数形式添加令牌并设置 Content-Type
标头:
requests.post('https://oauth2.googleapis.com/revoke', params={'token': credentials.token}, headers = {'content-type': 'application/x-www-form-urlencoded'})
Ruby
如需以编程方式撤消令牌,请向 oauth2.revoke
端点发出 HTTP 请求:
uri = URI('https://oauth2.googleapis.com/revoke') response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)
该令牌可以是访问令牌,也可以是刷新令牌。如果该令牌是访问令牌且具有相应的刷新令牌,则刷新令牌也会被撤消。
如果撤消操作成功处理,则响应的状态代码为 200
。对于错误情况,系统会返回状态代码 400
以及错误代码。
Node.js
如需以编程方式撤消令牌,请向 /revoke
端点发出 HTTPS POST 请求:
const https = require('https'); // Build the string for the POST request let postData = "token=" + userCredential.access_token; // Options for POST request to Google's OAuth 2.0 server to revoke a token let postOptions = { host: 'oauth2.googleapis.com', port: '443', path: '/revoke', method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Content-Length': Buffer.byteLength(postData) } }; // Set up the request const postReq = https.request(postOptions, function (res) { res.setEncoding('utf8'); res.on('data', d => { console.log('Response: ' + d); }); }); postReq.on('error', error => { console.log(error) }); // Post the request with data postReq.write(postData); postReq.end();
该令牌参数可以是访问令牌或刷新令牌。如果该令牌是访问令牌且具有相应的刷新令牌,则刷新令牌也会被撤消。
如果撤消操作成功处理,则响应的状态代码为 200
。对于错误情况,系统会返回状态代码 400
以及错误代码。
HTTP/REST
如需以编程方式撤消令牌,您的应用会向 https://oauth2.googleapis.com/revoke
发出请求,并将该令牌作为参数包含在内:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \ https://oauth2.googleapis.com/revoke?token={token}
该令牌可以是访问令牌,也可以是刷新令牌。如果该令牌是访问令牌且具有相应的刷新令牌,则刷新令牌也会被撤消。
如果撤消操作成功处理,则响应的 HTTP 状态代码为 200
。对于错误情况,系统会返回 HTTP 状态代码 400
以及错误代码。