本文說明網頁伺服器應用程式如何使用 Google API 用戶端程式庫或 Google OAuth 2.0 端點，實作 OAuth 2.0 授權來存取 Google API。
OAuth 2.0 可讓使用者與應用程式共用特定資料，同時保有使用者名稱、密碼和其他資訊的隱私。舉例來說，應用程式可以使用 OAuth 2.0 取得使用者授權，將檔案儲存在他們的 Google 雲端硬碟中。
這個 OAuth 2.0 流程專為使用者授權而設計。這項功能適用於可儲存機密資訊並維持狀態的應用程式。獲得適當授權的網頁伺服器應用程式可以在使用者與應用程式互動時，或在使用者離開應用程式後存取 API。
網頁伺服器應用程式通常也會使用 服務帳戶授權 API 要求，特別是呼叫 Cloud 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.
- API Library 會列出所有可用的 API，並按照產品系列和熱門程度分組。如果清單裡找不到您想啟用的 API，請使用搜尋功能，或點選所屬產品系列的「查看全部」。
- 選取要啟用的 API，然後按一下「Enable」按鈕。
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
建立授權憑證
凡是使用 OAuth 2.0 存取 Google API 的應用程式，都必須具備授權憑證，向 Google 的 OAuth 2.0 伺服器識別應用程式。下列步驟說明如何為專案建立憑證。應用程式隨後就能使用這些憑證，存取您為該專案啟用的 API。
- Go to the Credentials page.
- 按一下「建立用戶端」。
- 選取「網頁應用程式」應用程式類型。
- 填寫表單，然後按一下「建立」。使用 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 授權之前，建議您找出應用程式需要權限存取的範圍。
此外，我們建議您的應用程式透過漸進式授權程序要求授權範圍的存取權，也就是在相關使用情境中要求存取使用者資料。這項最佳做法可協助使用者輕鬆瞭解應用程式為何需要所要求的存取權。
「OAuth 2.0 API 範圍」文件列出您可能用來存取 Google API 的完整範圍清單。
語言專屬規定
如要執行本文中的任何程式碼範例，您需要 Google 帳戶、網際網路存取權和網路瀏覽器。如果您使用 API 用戶端程式庫，請參閱下方的語言專屬需求。
PHP
如要執行本文中的 PHP 程式碼範例，您需要：
- PHP 8.0 以上版本，並安裝指令列介面 (CLI) 和 JSON 擴充功能。
- Composer 依附元件管理工具。
-
PHP 適用的 Google API 用戶端程式庫：
composer require google/apiclient:^2.15.0
詳情請參閱 Google API PHP 專用用戶端程式庫。
Python
如要執行本文中的 Python 程式碼範例，請務必符合以下條件：
- Python 3.7 以上版本
- pip 套件管理工具。
- Google API Python 專用用戶端程式庫 2.0 版：
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 網頁應用程式架構。
pip install --upgrade flask
requestsHTTP 程式庫。pip install --upgrade requests
如果無法升級 Python 和相關遷移指南，請參閱 Google API Python 用戶端程式庫的版本資訊。
小茹
如要執行本文中的 Ruby 程式碼範例，請務必符合以下條件：
- Ruby 2.6 以上版本
-
Ruby 適用的 Google Auth 程式庫：
gem install googleauth
-
Google 雲端硬碟和日曆 Google API 的用戶端程式庫：
gem install google-apis-drive_v3 google-apis-calendar_v3
-
Sinatra Ruby 網路應用程式架構。
gem install sinatra
Node.js
如要執行本文中的 Node.js 程式碼範例，您需要：
- Node.js 的維護 LTS、有效 LTS 或目前版本。
-
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 端點，系統會產生網址，並在該網址上設定參數。
下方的分頁說明網路伺服器應用程式支援的授權參數。特定語言的範例也會說明如何使用用戶端程式庫或授權程式庫，設定可設定這些參數的物件。
PHP
下列程式碼片段會建立 Google\Client() 物件，定義授權要求中的參數。
該物件會使用 client_secret.json 檔案中的資訊來識別應用程式。(如要進一步瞭解該檔案，請參閱建立授權憑證)。這個物件也會識別應用程式要求授權存取的範圍，以及應用程式驗證端點的網址，該端點會處理 Google OAuth 2.0 伺服器的回應。最後，程式碼會設定選用的 access_type 和 include_granted_scopes 參數。
舉例來說，這段程式碼會要求以離線模式存取使用者的 Google 雲端硬碟中繼資料和日曆活動，但只能讀取資料：
use Google\Client; $client = new 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\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]); // 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 參數。
舉例來說，這段程式碼會要求以離線模式存取使用者的 Google 雲端硬碟中繼資料和日曆活動，但只能讀取資料：
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/drive.metadata.readonly', 'https://www.googleapis.com/auth/calendar.readonly']) # 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')
小茹
使用您建立的 client_secrets.json 檔案，在應用程式中設定用戶端物件。設定用戶端物件時，請指定應用程式需要存取的範圍，以及應用程式驗證端點的網址，該端點會處理 OAuth 2.0 伺服器的回應。
舉例來說，這段程式碼會要求以離線模式存取使用者的 Google 雲端硬碟中繼資料和日曆活動，但只能讀取資料：
require 'googleauth' require 'googleauth/web_user_authorizer' require 'googleauth/stores/redis_token_store' require 'google/apis/drive_v3' require 'google/apis/calendar_v3' # Required, call the from_file method to retrieve the client ID from a # client_secret.json file. client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json') # Required, scope value # Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar. scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY', 'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY'] # Required, Authorizers require a storage instance to manage long term persistence of # access and refresh tokens. token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new) # 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. callback_uri = '/oauth2callback' # 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. authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope, token_store, callback_uri)
應用程式會使用用戶端物件執行 OAuth 2.0 作業，例如產生授權要求 URL，以及將存取權杖套用至 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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar. const scopes = [ 'https://www.googleapis.com/auth/drive.metadata.readonly', 'https://www.googleapis.com/auth/calendar.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 and Google Calendar 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 連線。
Google 授權伺服器支援下列網路伺服器應用程式的查詢字串參數：
| 參數 | |||||||
|---|---|---|---|---|---|---|---|
client_id |
必要
應用程式的用戶端 ID。您可以在 中找到這個值。 |
||||||
redirect_uri |
必要
決定 API 伺服器在使用者完成授權流程後，將使用者重新導向至何處。這個值必須與 OAuth 2.0 用戶端的其中一個授權重新導向 URI 完全相符，您可以在用戶端的
中設定。如果這個值與所提供 請注意， |
||||||
response_type |
必要
決定 Google OAuth 2.0 端點是否傳回授權碼。 將網頁伺服器應用程式的參數值設為 |
||||||
scope |
必要
以空格分隔的範圍清單，用於識別應用程式可代表使用者存取的資源。這些值會提供資訊給 Google，決定要向使用者顯示的同意畫面。 範圍可讓應用程式僅要求存取其需要的資源，也能讓使用者控制對應用程式授予的存取量。因此，要求範圍的數量與取得使用者同意授權的可能性成反比。 建議應用程式盡可能在情境中要求授權範圍的存取權。透過漸進式授權，在相關情境中要求存取使用者資料，有助於使用者瞭解應用程式需要所要求存取權的原因。 |
||||||
access_type |
建議
指出使用者不在瀏覽器時，應用程式是否可以重新整理存取權權杖。有效參數值為 如果應用程式需要在使用者不在瀏覽器時重新整理存取權杖，請將值設為 |
||||||
state |
建議
指定應用程式用來維護授權要求與授權伺服器回應之間狀態的任何字串值。使用者同意或拒絕應用程式的存取要求後，伺服器會傳回您在網址查詢元件 ( 這個參數有多種用途，例如將使用者導向應用程式中的正確資源、傳送隨機數，以及防範跨網站要求偽造。由於 |
||||||
include_granted_scopes |
選填
允許應用程式使用漸進式授權，在相關情境中要求存取其他範圍。如果將這個參數的值設為 |
||||||
enable_granular_consent |
選填
預設為 Google 為應用程式啟用精細權限後，這個參數就不會再有任何作用。 |
||||||
login_hint |
選填
如果應用程式知道要驗證的使用者是誰，就可以使用這個參數向 Google 驗證伺服器提供提示。伺服器會使用提示簡化登入流程，方法是在登入表單中預先填入電子郵件欄位，或是選取適當的多重登入工作階段。 將參數值設為電子郵件地址或 |
||||||
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 網頁應用程式架構，將使用者重新導向至授權網址：
return flask.redirect(authorization_url)
小茹
- 產生網址，向 Google 的 OAuth 2.0 伺服器要求存取權：
auth_uri = authorizer.get_authorization_url(request: request)
- 將使用者重新導向至
auth_uri。
Node.js
-
使用步驟 1 中產生的網址
authorizationUrl，透過generateAuthUrl方法向 Google 的 OAuth 2.0 伺服器要求存取權。 -
將使用者重新導向至
authorizationUrl。res.redirect(authorizationUrl);
HTTP/REST
重新導向至 Google 授權伺服器的範例
以下是網址範例，為方便閱讀，已加入換行符和空格。
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& access_type=offline& include_granted_scopes=true& response_type=code& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/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 帳戶無法授權一或多個要求範圍。如要進一步瞭解管理員如何限制所有範圍或機密和受限範圍的存取權，直到明確授予 OAuth 用戶端 ID 存取權為止，請參閱 Google Workspace 管理員說明文章「 控管哪些第三方應用程式和內部應用程式可存取 Google Workspace 資料」。
disallowed_useragent
授權端點顯示在 Google 的 OAuth 2.0 政策禁止使用的內嵌使用者代理程式中。
Android
Android 開發人員在 android.webkit.WebView 中開啟授權要求時，可能會看到這則錯誤訊息。開發人員應改用 Android 程式庫，例如 Google Sign-In for Android 或 OpenID Foundation 的 AppAuth for Android。
如果 Android 應用程式在內嵌使用者代理程式中開啟一般網頁連結，且使用者從您的網站前往 Google 的 OAuth 2.0 授權端點，網頁開發人員可能會遇到這個錯誤。開發人員應允許一般連結在作業系統的預設連結處理常式中開啟，包括 Android 應用程式連結處理常式或預設瀏覽器應用程式。Android 自訂分頁程式庫也是支援的選項。
iOS
iOS 和 macOS 開發人員在 WKWebView 中開啟授權要求時，可能會遇到這項錯誤。開發人員應改用 iOS 程式庫，例如 Google Sign-In for iOS 或 OpenID Foundation 的 AppAuth for iOS。
如果 iOS 或 macOS 應用程式在內嵌的使用者代理程式中開啟一般網頁連結，且使用者從您的網站前往 Google 的 OAuth 2.0 授權端點，網頁開發人員可能會遇到這個錯誤。開發人員應允許一般連結在作業系統的預設連結處理常式中開啟，包括通用連結處理常式或預設瀏覽器應用程式。SFSafariViewController 程式庫也是支援的選項。
org_internal
要求中的 OAuth 用戶端 ID 屬於專案，該專案限制只能存取特定 Google Cloud 機構中的 Google 帳戶。如要進一步瞭解這個設定選項，請參閱「設定 OAuth 同意畫面」說明文章中的「使用者類型」一節。
invalid_client
OAuth 用戶端密鑰不正確。檢查 OAuth 用戶端設定，包括用於這項要求的用戶端 ID 和密鑰。
deleted_client
用來提出要求的 OAuth 用戶端已遭刪除。您可以手動刪除，也可以讓系統在未使用的用戶端 中自動刪除。刪除用戶端後，您可以在 30 天內還原。 瞭解詳情 。
invalid_grant
重新整理存取權杖或使用增量授權時，權杖可能已過期或失效。 再次驗證使用者身分，並徵求使用者同意，以取得新權杖。如果持續看到這則錯誤訊息，請確認應用程式設定正確無誤，且要求中使用的權杖和參數正確無誤。否則，使用者帳戶可能已遭刪除或停用。
redirect_uri_mismatch
授權要求中傳遞的 redirect_uri 與 OAuth 用戶端 ID 的授權重新導向 URI 不符。在
中，查看已授權的重新導向 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 雲端硬碟中的檔案中繼資料，以及查看 Google 日曆活動的唯讀存取權：
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& access_type=offline& include_granted_scopes=true& response_type=code& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
完成 OAuth 2.0 流程後，您應該會重新導向至 http://localhost/oauth2callback，除非本機在該地址提供檔案，否則可能會產生 404 NOT FOUND 錯誤。下一個步驟會詳細說明使用者重新導向回應用程式時，URI 中傳回的資訊。
步驟 5：以授權碼換取更新和存取權杖
網頁伺服器收到授權碼後，即可用授權碼交換存取權杖。
PHP
如要將授權碼換成存取權杖，請使用 fetchAccessTokenWithAuthCode 方法：
$access_token = $client->fetchAccessTokenWithAuthCode($_GET['code']);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/drive.metadata.readonly'], 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, 'granted_scopes': credentials.granted_scopes}
小茹
在回呼頁面上，使用 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 |
從 取得的用戶端 ID。 |
client_secret |
從 取得的用戶端密鑰。 |
code |
初始要求傳回的授權碼。 |
grant_type |
如 OAuth 2.0 規格所述，這個欄位的值必須設為 authorization_code。 |
redirect_uri |
專案在
中列出的其中一個重新導向 URI。client_id |
以下程式碼片段顯示要求範例：
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，這個欄位才會出現在回應中。
|
refresh_token_expires_in |
重新整理權杖的剩餘有效時間 (以秒為單位)。只有在使用者授予時間限制存取權時，系統才會設定這個值。 |
scope |
access_token授予的存取權範圍，以不分大小寫的字串清單表示，並以空格分隔。 |
token_type |
傳回的權杖類型。此時，這個欄位的值一律會設為 Bearer。 |
以下程式碼片段為回應範例：
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
錯誤
以授權碼換取存取權杖時，您可能會遇到下列錯誤，而不是預期的回應。下表列出常見的錯誤代碼和建議解決方法。
invalid_grant
提供的授權碼無效或格式有誤。如要要求新驗證碼，請重新啟動 OAuth 程序，再次提示使用者同意。
步驟 6：檢查使用者授予的範圍
要求多項權限 (範圍) 時，使用者可能不會授予應用程式所有權限。應用程式必須驗證實際授予的範圍，並妥善處理部分權限遭拒的情況，通常是停用依賴這些遭拒範圍的功能。
但也有例外情況。如果 Google Workspace Enterprise 應用程式已啟用網域範圍的授權委派，或是標示為信任，系統就會略過詳細權限同意畫面。這類應用程式不會顯示適當的權限同意畫面。應用程式會收到所有要求的範圍，或完全沒有。
詳情請參閱「如何處理精細權限」。
PHP
如要檢查使用者已授予哪些範圍，請使用 getGrantedScope() 方法：
// Space-separated string of granted scopes if it exists, otherwise null. $granted_scopes = $client->getOAuth2Service()->getGrantedScope(); // Determine which scopes user granted and build a dictionary $granted_scopes_dict = [ 'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY), 'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY) ];
Python
傳回的 credentials 物件具有 granted_scopes 屬性，這是使用者授予應用程式的範圍清單。
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, 'granted_scopes': credentials.granted_scopes}
下列函式會檢查使用者已授予應用程式哪些範圍。
def check_granted_scopes(credentials): features = {} if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['granted_scopes']: features['drive'] = True else: features['drive'] = False if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']: features['calendar'] = True else: features['calendar'] = False return features
小茹
如要一次要求多個範圍，請檢查 credentials 物件的 scope 屬性，瞭解已授予哪些範圍。
# User authorized the request. Now, check which scopes were granted. if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY) # User authorized read-only Drive activity permission. # Calling the APIs, etc else # User didn't authorize read-only Drive activity permission. # Update UX and application accordingly end # Check if user authorized Calendar read permission. if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY) # User authorized Calendar read permission. # Calling the APIs, etc. else # User didn't authorize Calendar read permission. # Update UX and application accordingly end
Node.js
如要一次要求多個範圍，請檢查 tokens 物件的 scope 屬性，瞭解已授予哪些範圍。
// User authorized the request. Now, check which scopes were granted. if (tokens.scope.includes('https://www.googleapis.com/auth/drive.metadata.readonly')) { // User authorized read-only Drive activity permission. // Calling the APIs, etc. } else { // User didn't authorize read-only Drive activity permission. // Update UX and application accordingly } // Check if user authorized Calendar read permission. if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly')) { // User authorized Calendar read permission. // Calling the APIs, etc. } else { // User didn't authorize Calendar read permission. // Update UX and application accordingly }
HTTP/REST
如要檢查使用者是否已授予應用程式特定範圍的存取權，請檢查存取權杖回應中的 scope 欄位。存取權範圍 (以空格分隔的字串清單表示，且區分大小寫)。
舉例來說，下列存取權杖回應範例指出，使用者已授予應用程式唯讀存取雲端硬碟活動和日曆活動的權限：
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
呼叫 Google API
PHP
如要使用存取權杖呼叫 Google API，請完成下列步驟：
- 如要將存取權杖套用至新的
Google\Client物件 (例如，您將存取權杖儲存在使用者工作階段中)，請使用setAccessToken方法：$client->setAccessToken($access_token); - 為要呼叫的 API 建構服務物件。您要呼叫 API 時，請將已授權的
Google\Client物件提供給建構函式，即可建構服務物件。舉例來說，如要呼叫 Drive API：$drive = new Google\Service\Drive($client); - 使用
服務物件提供的介面，向 API 服務提出要求。
舉例來說，如要列出已通過驗證的使用者 Google 雲端硬碟中的檔案：
$files = $drive->files->listFiles(array());
Python
取得存取權杖後，應用程式就能使用該權杖，代表特定使用者帳戶或服務帳戶授權 API 要求。使用使用者專屬的授權憑證，為要呼叫的 API 建構服務物件，然後使用該物件發出已授權的 API 要求。
- 為要呼叫的 API 建構服務物件。您可以使用
googleapiclient.discovery程式庫的build方法，並提供 API 名稱、版本和使用者憑證，建構服務物件： 舉例來說，如要呼叫 Drive API 第 3 版：from googleapiclient.discovery import build drive = build('drive', 'v2', credentials=credentials)
- 使用服務物件提供的介面，向 API 服務提出要求。
舉例來說，如要列出已通過驗證的使用者 Google 雲端硬碟中的檔案：
files = drive.files().list().execute()
小茹
取得存取權杖後，應用程式就能使用該權杖，代表特定使用者帳戶或服務帳戶提出 API 要求。使用使用者專屬的授權憑證，為要呼叫的 API 建構服務物件，然後使用該物件發出已授權的 API 要求。
- 為要呼叫的 API 建構服務物件。
舉例來說，如要呼叫 Drive API 第 3 版：
drive = Google::Apis::DriveV3::DriveService.new
- 在服務上設定憑證：
drive.authorization = credentials
- 使用服務物件提供的介面，向 API 服務提出要求。
舉例來說，如要列出已通過驗證的使用者 Google 雲端硬碟中的檔案：
files = drive.list_files
或者，您也可以為每個方法提供授權，方法是將 options 參數提供給方法：
files = drive.list_files(options: { authorization: credentials })
Node.js
取得存取權杖並將其設為 OAuth2 物件後，即可使用該物件呼叫 Google API。應用程式可以使用該權杖，代表特定使用者帳戶或服務帳戶授權 API 要求。為要呼叫的 API 建構服務物件。
舉例來說，下列程式碼會使用 Google Drive 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
應用程式取得存取權杖後，如果 API 要求的存取範圍已獲授權，您就可以使用權杖代表特定使用者帳戶呼叫 Google API。如要這麼做，請在 API 要求中加入存取權杖，方法是加入 access_token 查詢參數或 Authorization HTTP 標頭 Bearer 值。如果可以，請盡量使用 HTTP 標頭，因為查詢字串通常會顯示在伺服器記錄中。在大多數情況下，您可以使用用戶端程式庫設定對 Google API 的呼叫 (例如呼叫 Drive Files API 時)。
您可以在 OAuth 2.0 Playground 試用所有 Google API，並查看其範圍。
HTTP GET 範例
使用 Authorization: Bearer HTTP 標頭呼叫
drive.files 端點 (Drive Files API) 時，可能如下所示。請注意，您必須指定自己的存取權杖：
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
以下是使用 access_token 查詢字串參數，對經過驗證的使用者呼叫相同 API 的範例：
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl 範例
您可以使用 curl 指令列應用程式測試這些指令。以下是使用 HTTP 標頭選項的範例 (建議採用)：
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
或者，您也可以使用查詢字串參數選項：
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
完整範例
使用者驗證並同意應用程式存取 Google 雲端硬碟中繼資料後，以下範例會列印使用者 Google 雲端硬碟中的檔案清單 (JSON 格式)。
PHP
如要執行這個範例：
- 在 API Console中，將本機的網址新增至重新導向網址清單。舉例來說，請新增
http://localhost:8080。 - 建立新目錄並切換至該目錄。例如：
mkdir ~/php-oauth2-example cd ~/php-oauth2-example
- 使用 Composer 安裝 PHP 適用的 Google API 用戶端程式庫：
composer require google/apiclient:^2.15.0
- 建立
index.php和oauth2callback.php檔案，並加入以下內容。 - 使用 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_secret.json'); // User granted permission as an access token is in the session. if (isset($_SESSION['access_token']) && $_SESSION['access_token']) { $client->setAccessToken($_SESSION['access_token']); // Check if user granted Drive permission if ($_SESSION['granted_scopes_dict']['Drive']) { echo "Drive feature is enabled."; echo "</br>"; $drive = new Drive($client); $files = array(); $response = $drive->files->listFiles(array()); foreach ($response->files as $file) { echo "File: " . $file->name . " (" . $file->id . ")"; echo "</br>"; } } else { echo "Drive feature is NOT enabled."; echo "</br>"; } // Check if user granted Calendar permission if ($_SESSION['granted_scopes_dict']['Calendar']) { echo "Calendar feature is enabled."; echo "</br>"; } else { echo "Calendar feature is NOT enabled."; echo "</br>"; } } else { // Redirect users to outh2call.php which redirects users to Google OAuth 2.0 $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(); // Required, call the setAuthConfig function to load authorization credentials from // client_secret.json file. $client->setAuthConfigFile('client_secret.json'); $client->setRedirectUri('http://' . $_SERVER['HTTP_HOST']. $_SERVER['PHP_SELF']); // Required, to set the scope value, call the addScope function. $client->addScope([Google\Service\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]); // Enable incremental authorization. Recommended as a best practice. $client->setIncludeGrantedScopes(true); // 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"); // Generate a URL for authorization as it doesn't contain code and error if (!isset($_GET['code']) && !isset($_GET['error'])) { // Generate and set state value $state = bin2hex(random_bytes(16)); $client->setState($state); $_SESSION['state'] = $state; // Generate a url that asks permissions. $auth_url = $client->createAuthUrl(); header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL)); } // User authorized the request and authorization code is returned to exchange access and // refresh tokens. if (isset($_GET['code'])) { // Check the state value if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['state']) { die('State mismatch. Possible CSRF attack.'); } // Get access and refresh tokens (if access_type is offline) $token = $client->fetchAccessTokenWithAuthCode($_GET['code']); /** Save access and refresh token to the session variables. * ACTION ITEM: In a production app, you likely want to save the * refresh token in a secure persistent storage instead. */ $_SESSION['access_token'] = $token; $_SESSION['refresh_token'] = $client->getRefreshToken(); // Space-separated string of granted scopes if it exists, otherwise null. $granted_scopes = $client->getOAuth2Service()->getGrantedScope(); // Determine which scopes user granted and build a dictionary $granted_scopes_dict = [ 'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY), 'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY) ]; $_SESSION['granted_scopes_dict'] = $granted_scopes_dict; $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/'; header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL)); } // An error response e.g. error=access_denied if (isset($_GET['error'])) { echo "Error: ". $_GET['error']; } ?>
Python
本範例使用 Flask 架構。這個指令會在 http://localhost:8080 執行網路應用程式，供您測試 OAuth 2.0 流程。前往該網址後，您應該會看到五個連結：
- 呼叫 Drive API：如果使用者授予權限，這個連結會導向一個頁面，嘗試執行範例 API 要求。如有必要，系統會啟動授權流程。 如果成功，網頁會顯示 API 回應。
- 呼叫 Calendar API 的模擬頁面：這個連結指向的模擬頁面會嘗試執行 Calendar API 要求範例 (如果使用者已授予權限)。如有必要，系統會啟動授權流程。如果成功，網頁會顯示 API 回應。
- 直接測試授權流程：這個連結會指向一個頁面，嘗試讓使用者完成授權流程。應用程式會要求權限，代表使用者提交已授權的 API 要求。
- 撤銷目前憑證：這個連結會將您導向至一個頁面， 撤銷使用者已授予應用程式的權限。
- 清除 Flask 工作階段憑證：這個連結會清除儲存在 Flask 工作階段中的授權憑證。這樣一來，您就能瞭解使用者在新的工作階段中執行 API 要求時，會發生什麼情況 (前提是使用者已授予應用程式權限)。此外，您也可以查看 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" # The OAuth 2.0 access scope allows for access to the # authenticated user's account and requires requests to use an SSL connection. SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly', 'https://www.googleapis.com/auth/calendar.readonly'] API_SERVICE_NAME = 'drive' API_VERSION = 'v2' 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('/drive') def drive_api_request(): if 'credentials' not in flask.session: return flask.redirect('authorize') features = flask.session['features'] if features['drive']: # Load credentials from the session. credentials = google.oauth2.credentials.Credentials( **flask.session['credentials']) drive = googleapiclient.discovery.build( API_SERVICE_NAME, API_VERSION, credentials=credentials) files = drive.files().list().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(**files) else: # User didn't authorize read-only Drive activity permission. # Update UX and application accordingly return '<p>Drive feature is not enabled.</p>' @app.route('/calendar') def calendar_api_request(): if 'credentials' not in flask.session: return flask.redirect('authorize') features = flask.session['features'] if features['calendar']: # User authorized Calendar read permission. # Calling the APIs, etc. return ('<p>User granted the Google Calendar read permission. '+ 'This sample code does not include code to call Calendar</p>') else: # User didn't authorize Calendar read permission. # Update UX and application accordingly return '<p>Calendar feature is not enabled.</p>' @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 credentials = credentials_to_dict(credentials) flask.session['credentials'] = credentials # Check which scopes user granted features = check_granted_scopes(credentials) flask.session['features'] = features return flask.redirect('/') @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, 'granted_scopes': credentials.granted_scopes} def check_granted_scopes(credentials): features = {} if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['granted_scopes']: features['drive'] = True else: features['drive'] = False if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']: features['calendar'] = True else: features['calendar'] = False return features 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' # This disables the requested scopes and granted scopes check. # If users only grant partial request, the warning would not be thrown. os.environ['OAUTHLIB_RELAX_TOKEN_SCOPE'] = '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)
小茹
本範例使用 Sinatra 架構。
require 'googleauth' require 'googleauth/web_user_authorizer' require 'googleauth/stores/redis_token_store' require 'google/apis/drive_v3' require 'google/apis/calendar_v3' require 'sinatra' configure do enable :sessions # Required, call the from_file method to retrieve the client ID from a # client_secret.json file. set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json') # Required, scope value # Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar. scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY', 'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY'] # Required, Authorizers require a storage instance to manage long term persistence of # access and refresh tokens. set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new) # 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. set :callback_uri, '/oauth2callback' # 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. set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope, settings.token_store, callback_uri: settings.callback_uri) end get '/' do # NOTE: Assumes the user is already authenticated to the app user_id = request.session['user_id'] # Fetch stored credentials for the user from the given request session. # nil if none present credentials = settings.authorizer.get_credentials(user_id, request) if credentials.nil? # Generate a url that asks the user to authorize requested scope(s). # Then, redirect user to the url. redirect settings.authorizer.get_authorization_url(request: request) end # User authorized the request. Now, check which scopes were granted. if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY) # User authorized read-only Drive activity permission. # Example of using Google Drive API to list filenames in user's Drive. drive = Google::Apis::DriveV3::DriveService.new files = drive.list_files(options: { authorization: credentials }) "<pre>#{JSON.pretty_generate(files.to_h)}</pre>" else # User didn't authorize read-only Drive activity permission. # Update UX and application accordingly end # Check if user authorized Calendar read permission. if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY) # User authorized Calendar read permission. # Calling the APIs, etc. else # User didn't authorize Calendar read permission. # Update UX and application accordingly end end # Receive the callback from Google's OAuth 2.0 server. get '/oauth2callback' do # Handle the result of the oauth callback. Defers the exchange of the code by # temporarily stashing the results in the user's session. target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request) redirect target_url end
Node.js
如要執行這個範例：
-
在 API Console中，將本機的網址新增至重新導向網址清單。舉例來說，新增
http://localhost。 - 請確認您已安裝 Node.js 的維護 LTS、有效 LTS 或目前版本。
-
建立新目錄並切換至該目錄。例如：
mkdir ~/nodejs-oauth2-example cd ~/nodejs-oauth2-example
-
使用 npm 安裝 Node.js 適用的 Google API 用戶端程式庫：
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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar. const scopes = [ 'https://www.googleapis.com/auth/drive.metadata.readonly', 'https://www.googleapis.com/auth/calendar.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 and Google Calendar 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; // User authorized the request. Now, check which scopes were granted. if (tokens.scope.includes('https://www.googleapis.com/auth/drive.metadata.readonly')) { // User authorized read-only Drive activity permission. // 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.'); } }); } else { // User didn't authorize read-only Drive activity permission. // Update UX and application accordingly } // Check if user authorized Calendar read permission. if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly')) { // User authorized Calendar read permission. // Calling the APIs, etc. } else { // User didn't authorize Calendar read permission. // Update UX and application accordingly } } }); // 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(8080); } main().catch(console.error);
HTTP/REST
這個 Python 範例使用 Flask 架構和 Requests 程式庫，示範 OAuth 2.0 網頁流程。建議您使用 Python 適用的 Google API 用戶端程式庫來執行這項流程。(Python 分頁中的範例會使用用戶端程式庫)。
import json import flask import requests app = flask.Flask(__name__) # To get these credentials (CLIENT_ID CLIENT_SECRET) and for your application, visit # https://console.cloud.google.com/apis/credentials. CLIENT_ID = '123456789.apps.googleusercontent.com' CLIENT_SECRET = 'abc123' # Read from a file or environmental variable in a real app # Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar. SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly' # 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. 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: # User authorized the request. Now, check which scopes were granted. if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['scope']: # User authorized read-only Drive activity permission. # Example of using Google Drive API to list filenames in user's Drive. headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])} req_uri = 'https://www.googleapis.com/drive/v2/files' r = requests.get(req_uri, headers=headers).text else: # User didn't authorize read-only Drive activity permission. # Update UX and application accordingly r = 'User did not authorize Drive permission.' # Check if user authorized Calendar read permission. if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['scope']: # User authorized Calendar read permission. # Calling the APIs, etc. r += 'User authorized Calendar permission.' else: # User didn't authorize Calendar read permission. # Update UX and application accordingly r += 'User did not authorize Calendar permission.' return r @app.route('/oauth2callback') def oauth2callback(): if 'code' not in flask.request.args: state = str(uuid.uuid4()) flask.session['state'] = state # Generate a url that asks permissions for the Drive activity # and Google Calendar scope. Then, redirect user to the url. 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'} # Exchange authorization code for access and refresh tokens (if access_type is offline) 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 必須遵守下列規則。如要瞭解下方提及的網域、主機、路徑、查詢、結構定義和使用者資訊，請參閱 RFC 3986 第 3 節。
| 驗證規則 | |
|---|---|
| 配置 |
重新導向 URI 必須使用 HTTPS 配置，而非純 HTTP。本機主機 URI (包括本機主機 IP 位址 URI) 不受這項規則限制。 |
| 主機 |
主機不得為原始 IP 位址。本機主機 IP 位址不受這項規則限制。 |
| 網域 |
“googleusercontent.com”。goo.gl)，除非應用程式擁有該網域。此外，如果擁有縮網址網域的應用程式選擇重新導向至該網域，重新導向 URI 的路徑必須包含 “/google-callback/” 或以 “/google-callback” 結尾。 |
| Userinfo |
重新導向 URI 不得包含 userinfo 子元件。 |
| 路徑 |
重新導向 URI 不得包含路徑遍歷 (也稱為目錄回溯)，以 |
| 查詢 |
重新導向 URI 不得包含開放式重新導向。 |
| Fragment |
重新導向 URI 不得包含片段元件。 |
| 字元數 |
重新導向 URI 不得包含特定字元，包括：
|
增量授權
在 OAuth 2.0 通訊協定中，應用程式會要求授權存取資源，這些資源由範圍識別。在需要資源時要求授權，是提供最佳使用者體驗的做法。為啟用這項做法，Google 的授權伺服器支援增量授權。這項功能可讓您視需要要求範圍，如果使用者授予新範圍的權限，系統會傳回授權碼，該授權碼可換取權杖，其中包含使用者授予專案的所有範圍。
舉例來說，如果應用程式可讓使用者試聽音樂曲目及製作混音，可能只需要極少的資源 (或許只有登入者的名稱)，不過，如要儲存完成的組合，必須存取對方的 Google 雲端硬碟。如果應用程式只在實際需要時要求存取 Google 雲端硬碟，大多數使用者都會覺得很自然。
在這個案例中，應用程式可能會在登入時要求 openid 和 profile 範圍，執行基本登入作業，然後在首次要求儲存混音時，要求 https://www.googleapis.com/auth/drive.file 範圍。
如要實作增量授權，請完成要求存取權杖的一般流程，但請務必在授權要求中加入先前授予的範圍。這種做法可讓應用程式不必管理多個存取權杖。
透過增量授權取得的存取權杖適用下列規則：
- 您可以使用這個權杖，存取與新合併授權中任何範圍對應的資源。
- 使用複合授權的重新整理權杖取得存取權杖時，存取權杖代表複合授權，可用於回應中包含的任何
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')
小茹
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
GET https://accounts.google.com/o/oauth2/v2/auth? client_id=your_client_id& response_type=code& state=state_parameter_passthrough_value& scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly& redirect_uri=https%3A//oauth2.example.com/code& prompt=consent& include_granted_scopes=true
重新整理存取權杖 (離線存取)
存取權杖會定期過期，並成為相關 API 要求的無效憑證。如果您要求存取與權杖相關聯的範圍，即可重新整理存取權杖，不必提示使用者授予權限 (包括使用者不在時)。
- 如果您使用 Google API 用戶端程式庫，只要為離線存取設定用戶端物件，該物件就會視需要重新整理存取權杖。
- 如果您未使用用戶端程式庫，請在將使用者重新導向至 Google 的 OAuth 2.0 伺服器時，將
access_typeHTTP 查詢參數設為offline。在這種情況下，當您將授權碼換成存取權杖時，Google 的授權伺服器會傳回更新權杖。接著，如果存取權杖過期 (或在任何其他時間)，您可以使用更新權杖取得新的存取權杖。
如果應用程式需要在使用者不在時存取 Google API，就必須要求離線存取權。舉例來說，如果應用程式會執行備份服務或在預先決定的時間執行動作，就必須能在使用者不在時重新整理存取權杖。預設存取樣式稱為 online。
伺服器端網頁應用程式、已安裝的應用程式和裝置都會在授權程序中取得重新整理權杖。用戶端 (JavaScript) 網頁應用程式通常不會使用重新整理權杖。
PHP
如果應用程式需要離線存取 Google API，請將 API 用戶端的存取類型設為 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。用戶端物件會視需要重新整理存取權杖。
小茹
如果應用程式需要離線存取 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
如要重新整理存取權杖，應用程式會將 HTTPS POST 要求傳送至 Google 的授權伺服器 (https://oauth2.googleapis.com/token)，其中包含下列參數：
| 欄位 | |
|---|---|
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 https://www.googleapis.com/auth/calendar.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'})
小茹
如要以程式輔助方式撤銷權杖，請向 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 和錯誤碼。
以時間為依據的存取權
使用者可以授予應用程式限時存取權，讓應用程式在一段時間內存取資料，以完成特定操作。在同意聲明流程中，使用者可以在特定 Google 產品中選擇授予限時存取權。例如 Data Portability API 可讓使用者一次性轉移資料。
使用者授予應用程式限時存取權時，更新權杖會在指定時間後失效。請注意，在特定情況下，重新整理權杖可能會提早失效；詳情請參閱這些案例。在這種情況下，授權碼交換回應中傳回的 refresh_token_expires_in 欄位，代表重新整理權杖到期前的剩餘時間。
導入跨帳戶防護功能
為保護使用者帳戶，您應採取額外步驟，利用 Google 的跨帳戶保護服務實作跨帳戶保護機制。這項服務可讓您訂閱安全性事件通知，向應用程式提供使用者帳戶重大變更的相關資訊。接著，您就能根據決定如何回應活動，採取適當行動。
Google 跨帳戶保護服務傳送給應用程式的事件類型包括：
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
如要進一步瞭解如何實作跨帳戶保護機制，以及查看可用事件的完整清單，請參閱「 透過跨帳戶保護機制保護使用者帳戶 」頁面。