本文件說明如何使用 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 所屬的產品系列中按一下「查看全部」。
- 選取要啟用的 API，然後按一下「啟用」按鈕。
- 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.
- 按一下「Create Client」。
- 選取「網頁應用程式」應用程式類型。
- 填寫表單，然後按一下「建立」。使用 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 程式碼範例，您需要：
- 已安裝指令列介面 (CLI) 和 JSON 擴充功能的 PHP 8.0 以上版本。
- Composer 依附元件管理工具。
-
PHP 適用的 Google API 用戶端程式庫：
composer require google/apiclient:^2.15.0
詳情請參閱 適用於 PHP 的 Google API 用戶端程式庫。
Python
如要執行本文中的 Python 程式碼範例，您需要：
- Python 3.7 以上版本
- pip 套件管理工具。
- Python 適用的 Google API 用戶端程式庫 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 驗證程式庫：
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 作業，例如產生授權要求網址，以及將存取權憑證套用至 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 |
建議
指定應用程式用於在授權要求和授權伺服器回應之間維持狀態的任何字串值。在使用者同意或拒絕應用程式的存取要求後，伺服器會傳回您在 您可以將這個參數用於多種用途，例如將使用者導向應用程式中的正確資源、傳送 Nonce，以及減輕跨網站請求偽造問題。由於 |
||||||
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
generateAuthUrl方法產生的網址authorizationUrl，向 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 登入或 OpenID Foundation 的 AppAuth for Android。
如果 Android 應用程式在嵌入的使用者代理程式中開啟一般網頁連結，且使用者從您的網站前往 Google 的 OAuth 2.0 授權端點，網頁開發人員可能會遇到這個錯誤。開發人員應允許一般連結在作業系統的預設連結處理常式中開啟，包括 Android 應用程式連結處理常式或預設瀏覽器應用程式。Android 自訂分頁程式庫也是支援的選項。
iOS
iOS 和 macOS 開發人員在 WKWebView 中開啟授權要求時，可能會遇到這個錯誤。開發人員應改用 iOS 程式庫，例如 Google 登入 (適用於 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 |
在指定 client_id 的
中，為專案列出的重新導向 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 |
您可以使用這項權杖取得新的存取權杖。更新憑證會在使用者撤銷存取權或更新憑證到期前有效。請注意，只有在您將 access_type 參數設為 Google 授權伺服器的初始要求中的 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 授予的存取權範圍，以空格分隔的字串清單表示，且區分大小寫。
舉例來說，下列存取權存取權杖回應範例表示使用者已授予應用程式存取權，可存取 Google 雲端硬碟活動和日曆活動的唯讀權限：
{ "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 雲端硬碟 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
完整範例
以下範例會在使用者驗證並同意應用程式存取使用者的雲端硬碟中繼資料後，以 JSON 格式列印使用者 Google 雲端硬碟中的檔案清單。
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 流程。前往該網址後，您應該會看到五個連結：
- 呼叫雲端硬碟 API：這個連結會導向至一個頁面，如果使用者授予權限，這個頁面會嘗試執行範例 API 要求。視需要啟動授權流程。如果成功，頁面會顯示 API 回應。
- 模擬呼叫 Calendar API 的頁面：這個連結會導向模擬頁面，如果使用者授予權限，該頁面會嘗試執行範例 Calendar 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" # 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。 - 請確認您已安裝維護 LTS、主動 LTS 或目前的 Node.js 版本。
-
建立新目錄並切換至該目錄。例如：
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
如要重新整理存取權杖，應用程式會向 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 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
如要進一步瞭解如何實作跨帳戶保護功能，以及查看可用的完整事件清單，請參閱「 透過跨帳戶保護功能保護使用者帳戶 」一文。