本文件說明安裝在手機、平板電腦和電腦等裝置上安裝的應用程式,如何利用 Google 的 OAuth 2.0 端點來授權存取 Google API。
OAuth 2.0 可讓使用者與應用程式共用特定資料,同時保有使用者名稱、密碼和其他資訊的隱私。舉例來說,應用程式可以透過 OAuth 2.0 取得使用者授權,讓他們將檔案儲存在 Google 雲端硬碟中。
已安裝的應用程式會發布至個別裝置,並假設這些應用程式無法保存密鑰。當使用者位於應用程式或應用程式在背景執行時,就能存取 Google API。
這項授權流程與網路伺服器應用程式所用的流程類似。主要差別在於安裝的應用程式必須開啟系統瀏覽器並提供本機重新導向 URI,才能處理來自 Google 授權伺服器的回應。
替代方案
針對行動應用程式,建議您使用 Android 或 iOS 版的 Google 登入功能。Google 登入用戶端程式庫可處理驗證和使用者授權,可能比此處所述的較低層級通訊協定更容易實作。
如果應用程式是在不支援系統瀏覽器的裝置上執行,或只有有限的輸入功能 (例如電視、遊戲主機、相機或印表機),請參閱電視和裝置的 OAuth 2.0 或在電視和有限輸入裝置上登入。
資料庫與示例
建議您使用下列程式庫與範例來實作本文件所述的 OAuth 2.0 流程:
必要條件
為專案啟用 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,或在其所屬的產品系列中按一下「View All」。
- 選取要啟用的 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.
- 按一下 [Create credentials] (建立憑證) > [OAuth client ID] (OAuth 用戶端 ID)。
- 以下各節說明 Google 授權伺服器支援的用戶端類型和重新導向方法。請選擇應用程式建議的用戶端類型、為 OAuth 用戶端命名,並視需要設定表單中的其他欄位。
Android
- 選取「Android」應用程式類型。
- 輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的 Credentials page 中,以識別用戶端。
- 輸入 Android 應用程式的套件名稱。這個值會在應用程式資訊清單檔案中
<manifest>
元素的package
屬性中定義。 - 輸入應用程式發行版本的 SHA-1 簽署憑證指紋。
- 如果應用程式使用 Google Play 應用程式簽署功能,請從 Play 管理中心的應用程式簽署頁面複製 SHA-1 指紋。
- 如果您管理自己的 KeyStore 和簽署金鑰,請使用 Java 隨附的 keytool 公用程式,以使用者可理解的格式列印憑證資訊。複製 keytool 輸出內容中
Certificate fingerprints
區段中的SHA1
值。詳情請參閱 Android 版 Google API 說明文件中的驗證用戶端。
- (選用) 驗證 Android 應用程式的擁有權。
- 按一下「建立」。
iOS
- 選取「iOS」iOS應用程式類型。
- 輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的 Credentials page 中,以識別用戶端。
- 輸入應用程式的軟體包 ID。軟體包 ID 是指應用程式資訊屬性清單資源檔案 (info.plist) 中 CFBundleIdentifier 鍵的值。這個值最常顯示在 Xcode 專案編輯器的「General」窗格或「Signing & Capabilities」窗格中。軟體包 ID 也會顯示在 Apple App Store Connect 網站上應用程式「應用程式資訊」頁面的「一般資訊」部分中。
- (選用)
如果應用程式是在 Apple 的 App Store 中發布,請輸入應用程式的 App Store ID。商店 ID 是一組數字字串,隨附於每個 Apple App Store 網址中。
- 在 iOS 或 iPadOS 裝置上開啟 Apple App Store 應用程式。
- 搜尋您的應用程式。
- 選取「分享」按鈕 (正方形和向上箭頭)。
- 選取「複製連結」。
- 將連結貼到文字編輯器中。App Store ID 是網址的最後部分。
範例:
https://apps.apple.com/app/google/id284815942
- (選用)
輸入您的團隊 ID。詳情請參閱 Apple 開發人員帳戶說明文件中的「找出團隊 ID」一節。
- 按一下「建立」。
紫光展銳
- 選取「Universal Windows Platform」(通用 Windows 平台) 應用程式類型。
- 輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的 Credentials page 中,以識別用戶端。
- 輸入應用程式的 12 個字元 Microsoft Store ID。您可以在 Microsoft 合作夥伴中心的「應用程式管理」專區的「應用程式身分」頁面找到這個值。
- 按一下「建立」。
如果是 UWP 應用程式,自訂 URI 配置的長度不得超過 39 個字元。
自訂 URI 配置 (Android、iOS、UWP)
自訂 URI 配置是一種深層連結,透過自訂定義的配置開啟應用程式。
在 Android 上使用自訂 URI 配置的替代方案使用 Android 版 Google 登入功能,將 OAuth 2.0 回應直接傳送至您的應用程式,無需使用重新導向 URI。
如何遷移至 Android SDK 專用的 Google 登入
如果您目前在 Android 上使用自訂配置來整合 OAuth,則必須完成以下動作,才能全面改用建議的 Android SDK 專用 Google 登入功能:
- 更新程式碼以使用 Google 登入 SDK。
- 停止支援 Google API 控制台中的自訂配置。
請按照下列步驟遷移至 Google 登入 Android SDK:
-
更新程式碼,使用 Google 登入 Android SDK:
-
檢查程式碼,找出向 Google 的 OAuth 2.0 伺服器傳送要求的位置。如果使用自訂配置,要求看起來會像這樣:
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirect
是上述範例的自訂配置重新導向 URI。如要進一步瞭解自訂 URI 配置值的格式,請參閱redirect_uri
參數定義。 -
記下設定 Google 登入 SDK 所需的
scope
和client_id
要求參數。 -
按照
開始將 Google 登入整合至 Android 應用程式的操作說明設定 SDK。您可以略過「取得後端伺服器的 OAuth 2.0 用戶端 ID」步驟,會重複使用在上一個步驟中擷取的
client_id
。 -
按照
啟用伺服器端 API 存取權的指示操作。這些步驟包括:
-
使用
getServerAuthCode
方法擷取您要求權限範圍的驗證碼。 - 將驗證碼傳送至應用程式的後端,以交換存取權及更新權杖。
- 使用擷取的存取權杖,代表使用者呼叫 Google API。
-
使用
-
檢查程式碼,找出向 Google 的 OAuth 2.0 伺服器傳送要求的位置。如果使用自訂配置,要求看起來會像這樣:
-
在 Google API 控制台中停用自訂配置的支援功能:
- 前往 OAuth 2.0 憑證清單,選取您的 Android 用戶端。
- 前往「進階設定」部分,取消勾選「啟用自訂 URI 配置」核取方塊,然後按一下「儲存」即可停用自訂 URI 配置支援。
啟用自訂 URI 配置
如果建議的替代方法不適用於您的情況,請按照以下操作說明,為 Android 用戶端啟用自訂 URI 配置:- 前往 OAuth 2.0 憑證清單,然後選取您的 Android 用戶端。
- 前往「進階設定」部分,勾選「啟用自訂 URI 配置」核取方塊,然後按一下「儲存」即可啟用自訂 URI 配置支援。
使用 Chrome Identity API,將 OAuth 2.0 回應直接傳送至應用程式,無須使用重新導向 URI。
驗證應用程式擁有權 (Android、Chrome)
您可以驗證應用程式的擁有權,降低應用程式遭到冒用的風險。
Android
如要完成驗證程序,您可以使用 Google Play 開發人員帳戶 (如果您有 Google Play 開發人員帳戶,且已在 Google Play 管理中心註冊應用程式)。您必須符合下列規定,才能成功驗證:
- 您必須在 Google Play 管理中心中註冊應用程式,並使用與要完成驗證程序的 Android OAuth 用戶端相同的套件名稱和 SHA-1 簽署憑證指紋。
- 您在 Google Play 管理中心必須具備該應用程式的「管理員」權限。 進一步瞭解 Google Play 管理中心的存取權管理。
在 Android 用戶端的「驗證應用程式擁有權」部分中,按一下「驗證擁有權」按鈕,完成驗證程序。
如果驗證成功,系統會顯示通知,確認驗證程序成功。否則,系統會顯示錯誤提示。
如要解決驗證失敗的問題,請嘗試下列做法:
- 請確認您要驗證的應用程式是 Google Play 管理中心的已註冊應用程式。
- 請確認您在 Google Play 管理中心擁有應用程式的「管理員」權限。
Chrome
如要完成驗證程序,請使用自己的 Chrome 線上應用程式商店開發人員帳戶。 要通過驗證,您必須符合以下條件:
- 你在 Chrome 線上應用程式商店開發人員資訊主頁中有一個已註冊的項目,項目 ID 必須與你要完成驗證程序的 Chrome Extension OAuth 用戶端項目 ID 相同。
- 您必須是 Chrome 線上應用程式商店商品的發布者。進一步瞭解如何在 Chrome 線上應用程式商店開發人員資訊主頁中管理存取權。
在 Chrome 擴充功能用戶端的「驗證應用程式擁有權」部分中,按一下 [驗證擁有權] 按鈕以完成驗證程序。
注意:授予帳戶存取權後,請稍等幾分鐘,然後完成驗證程序。
如果驗證成功,系統會顯示通知,確認驗證程序成功。否則,系統會顯示錯誤提示。
如要解決驗證失敗的問題,請嘗試下列做法:
回送 IP 位址 (macOS、Linux、Windows 電腦)
如要使用這個網址接收授權碼,您的應用程式必須監聽本機網路伺服器。這在許多平台上都有可能,但並非所有平台。不過,如果您的平台支援這項功能,我們才建議您使用這項機制來取得授權碼。
應用程式收到授權回應時,為求最佳可用性,應用程式應顯示 HTML 網頁,引導使用者關閉瀏覽器並返回應用程式,藉此做出回應。
建議用法 | macOS、Linux 和 Windows 電腦 (不含通用 Windows 平台) 應用程式 |
表單值 | 將應用程式類型設為「Desktop app」。 |
手動複製/貼上
識別存取權範圍
範圍可讓應用程式僅要求存取所需資源,同時讓使用者能控管對應用程式的存取權量。因此,要求的範圍數量與取得使用者同意聲明的可能性之間可能存在反轉關係。
開始實作 OAuth 2.0 授權前,建議您先找出應用程式需要權限存取的範圍。
OAuth 2.0 API 範圍文件列出了可用來存取 Google API 的範圍。
取得 OAuth 2.0 存取權杖
下列步驟說明您的應用程式如何與 Google OAuth 2.0 伺服器互動,以取得使用者的同意,允許他們代表使用者執行 API 要求。應用程式必須取得該同意聲明,才能執行需要使用者授權的 Google API 要求。
步驟 1:產生程式碼驗證器和驗證方式
Google 支援程式碼交換金鑰驗證 (PKCE) 通訊協定 (PKCE) 通訊協定,讓安裝版應用程式流程更安全。系統會為每個授權要求建立專屬代碼驗證器,並將轉換後的值 (名為「code_challenge」) 傳送至授權伺服器,以取得授權碼。
建立程式碼驗證器
code_verifier
是一種高熵密碼隨機字串,會使用未保留的字元 [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~",長度下限為 43 個字元,長度上限為 128 個字元。
程式碼驗證器必須具備足夠的資訊熵,才能難以猜測值。
建立程式碼驗證問題
我們支援兩種建立程式碼挑戰的方法。
程式碼驗證產生方法 | |
---|---|
S256 (建議) | 程式碼挑戰是程式碼驗證器的 Base64URL (不含邊框間距) 編碼 SHA256 雜湊。
|
普通 | 程式碼驗證值與上方產生的程式碼驗證器值相同。
|
步驟 2:傳送要求至 Google 的 OAuth 2.0 伺服器
如要取得使用者授權,請透過 https://accounts.google.com/o/oauth2/v2/auth
傳送要求至 Google 的授權伺服器。此端點會處理主動工作階段查詢、驗證使用者,並取得使用者同意聲明。端點只能透過安全資料傳輸層 (SSL) 存取,並拒絕 HTTP (非 SSL) 連線。
針對已安裝的應用程式,授權伺服器支援下列查詢字串參數:
參數 | |||||||
---|---|---|---|---|---|---|---|
client_id |
必要
應用程式的用戶端 ID。您可以在 API Console Credentials page中找到這個值。 |
||||||
redirect_uri |
必要
決定 Google 的授權伺服器傳送回應至應用程式的方式。已安裝的應用程式提供多種重新導向選項,您要使用特定的重新導向方法設定授權憑證。 這個值必須與 OAuth 2.0 用戶端的其中一個已授權重新導向 URI 完全相符,而您在用戶端的 API Console
Credentials page中已設定該用戶端。如果這個值與已授權的 URI 不相符,您會收到 下表列出每種方法適用的
|
||||||
response_type |
必要
判斷 Google OAuth 2.0 端點是否傳回授權碼。 針對已安裝的應用程式,將參數值設為 |
||||||
scope |
必要
以空格分隔的範圍清單,用於識別應用程式可代表使用者存取的資源。這些值會通知 Google 向使用者顯示的同意畫面。 範圍可讓應用程式僅要求存取所需資源,同時讓使用者能控管對應用程式的存取權量。因此,要求的範圍數量與取得使用者同意聲明的可能性之間存在反向關係。 |
||||||
code_challenge |
建議
指定經過編碼的 |
||||||
code_challenge_method |
建議
指定將 |
||||||
state |
建議
指定應用程式使用的任何字串值,在授權要求和授權伺服器回應之間維持狀態。使用者同意或拒絕應用程式的存取要求後,伺服器會傳回您在 這項參數可用於多種用途,例如將使用者導向應用程式中的正確資源、傳送 Nonce,以及減少跨網站要求偽造情形。由於 |
||||||
login_hint |
選用 如果應用程式知道要驗證哪位使用者,就能使用這個參數向 Google 驗證伺服器提供提示。伺服器會使用提示來簡化登入流程,方法是在登入表單中預先填入電子郵件欄位,或是選取適當的多登入工作階段。 將參數值設為電子郵件地址或 |
授權網址範例
下列分頁列出不同重新導向 URI 選項的授權網址範例。
這些網址相同,但 redirect_uri
參數值除外。網址也包含必要的 response_type
和 client_id
參數,以及選用的 state
參數。每個網址都包含換行符號和空格,方便使用者閱讀。
自訂 URI 配置
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
回送 IP 位址
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
步驟 3:Google 提示使用者表示同意
在這個步驟中,使用者可決定是否要將要求的存取權授予應用程式。在這個階段,Google 會顯示同意視窗,當中會顯示應用程式的名稱,以及應用程式向使用者授權憑證要求存取的 Google API 服務,以及授予存取權的範圍摘要。然後,使用者就可以同意授予應用程式要求的一或多個範圍的存取權,或是拒絕要求。
在這個階段中,應用程式會等候 Google OAuth 2.0 伺服器的回應,指出是否已授予任何存取權,因此您不需要採取任何行動。該回應會在下一個步驟中說明。
錯誤
傳送至 Google OAuth 2.0 授權端點的要求可能會顯示使用者顯示的錯誤訊息,而非預期的驗證和授權流程。以下列出常見的錯誤代碼和建議解決方法。
admin_policy_enforced
基於其 Google Workspace 管理員的政策,Google 帳戶無法授權給一或多個要求的範圍。如要進一步瞭解管理員如何限制存取所有範圍,或是機密和受限制範圍的存取權,請參閱 Google Workspace 管理員說明文章「 控管哪些第三方應用程式和內部應用程式可存取 Google Workspace 資料」。
disallowed_useragent
授權端點會顯示在 Google OAuth 2.0 政策不允許的嵌入使用者代理程式中。
Android
Android 開發人員可能會在 android.webkit.WebView
中開啟授權要求時,看到這則錯誤訊息。
開發人員應改用 Android 程式庫,例如 Android 版 Google 登入或 OpenID Foundation 的 Android AppAuth。
如果 Android 應用程式在內嵌使用者代理程式中開啟一般網頁連結,且使用者從您的網站前往 Google 的 OAuth 2.0 授權端點,就可能遇到這個錯誤。開發人員應允許在作業系統的預設連結處理常式中開啟一般連結,包括 Android 應用程式連結處理常式或預設的瀏覽器應用程式。此外,我們也支援「Android 自訂分頁」程式庫。
iOS
iOS 和 macOS 開發人員在 WKWebView
中開啟授權要求時,可能會發生這個錯誤。開發人員應改用 iOS 程式庫,例如 iOS 適用的 Google 登入或 OpenID Foundation 的 iOS 版 AppAuth。
如果 iOS 或 macOS 應用程式在內嵌使用者代理程式中開啟一般網頁連結,而使用者從您的網站前往 Google 的 OAuth 2.0 授權端點,就可能遇到這個錯誤。開發人員應允許在作業系統的預設連結處理常式中開啟一般連結,包括通用連結處理常式或預設的瀏覽器應用程式。此外,我們也支援 SFSafariViewController
程式庫選項。
org_internal
要求中的 OAuth 用戶端 ID 屬於專案,限制特定 Google Cloud 機構中的 Google 帳戶存取權。如要進一步瞭解這個設定選項,請參閱「設定 OAuth 同意畫面」說明文章中的「使用者類型」一節。
invalid_grant
如果您使用了程式碼驗證器和驗證方式,code_callenge
參數無效或遺失。確認 code_challenge
參數設定正確無誤。
重新整理存取權杖時,權杖可能已過期或已失效。再次驗證使用者,並要求使用者同意取得新權杖。如果您持續看到這個錯誤,請確認應用程式設定正確無誤,且在要求中使用正確的權杖和參數。否則,該使用者帳戶可能已遭刪除或停用。
redirect_uri_mismatch
授權要求中傳遞的 redirect_uri
與 OAuth 用戶端 ID 的授權重新導向 URI 不符。查看 Google API Console Credentials page中已授權的重新導向 URI。
傳遞的 redirect_uri
可能不適用於用戶端類型。
redirect_uri
參數可能是指已淘汰且系統不再支援的 OAuth 頻外 (OOB) 流程。如要更新整合作業,請參閱遷移指南。
invalid_request
您提交的要求有錯誤。可能的原因如下:
- 要求格式不正確
- 要求中缺少必要參數
- 要求使用了 Google 不支援的授權方法。使用建議的整合方法驗證 OAuth 整合作業
- 重新導向 URI 使用自訂配置:如果您看到以下錯誤訊息:「Chrome 應用程式不支援自訂 URI 配置」或「您的 Android 用戶端未啟用自訂 URI 配置」,代表您使用的是 Chrome 應用程式不支援的自訂 URI 配置,而且 Android 預設會停用此配置。進一步瞭解自訂 URI 配置替代方案
步驟 4:處理 OAuth 2.0 伺服器回應
應用程式接收授權回應的方式,取決於其使用的重新導向 URI 配置。無論配置為何,回應都會包含授權碼 (code
) 或錯誤 (error
)。舉例來說,error=access_denied
表示使用者已拒絕要求。
如果使用者授予應用程式存取權,您可以交換存取權杖和更新權杖,如下一個步驟所述。
步驟 5:交換更新及存取權杖所需的授權碼
如要交換存取權杖的授權碼,請呼叫 https://oauth2.googleapis.com/token
端點,並設定下列參數:
欄位 | |
---|---|
client_id |
從 API Console Credentials page取得的用戶端 ID。 |
client_secret |
從 API Console Credentials page取得的用戶端密鑰。 |
code |
從初始要求傳回的授權碼。 |
code_verifier |
您在步驟 1 中建立的程式碼驗證器。 |
grant_type |
如 OAuth 2.0 規格中的定義,這個欄位的值必須設為 authorization_code 。 |
redirect_uri |
在指定的 client_id 的 API Console
Credentials page 中,專案的其中一個重新導向 URI。 |
以下程式碼片段為要求範例:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Google 會傳回包含短期存取權杖和更新權杖的 JSON 物件來回應這項要求。
回應包含下列欄位:
欄位 | |
---|---|
access_token |
應用程式傳送用於授權 Google API 要求的憑證。 |
expires_in |
存取權杖的剩餘生命週期 (以秒為單位)。 |
id_token |
注意:只有在要求包含身分範圍 (例如 openid 、profile 或 email ) 時,才會傳回這個屬性。這個值是 JSON Web Token (JWT),內含使用者相關數位簽署的身分資訊。 |
refresh_token |
可以用來取得新的存取權杖的憑證。重新整理權杖的效力會持續至使用者撤銷存取權為止。請注意,系統一律會針對已安裝的應用程式傳回重新整理權杖。 |
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", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
呼叫 Google API
應用程式取得存取權杖後,如果您已獲得 API 所需的存取權範圍,就能使用權杖代表指定使用者帳戶呼叫 Google API。方法是加入 access_token
查詢參數或 Authorization
HTTP 標頭 Bearer
值,在向 API 發出的要求中加入存取權杖。請盡可能使用 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
重新整理存取權杖
存取權杖會定期過期,並成為相關 API 要求的無效憑證。如果您要求存取該權杖相關聯的範圍,則可更新存取權杖,而不必提示使用者授予權限 (包括沒有使用者時)。
如要更新存取權杖,應用程式會將 HTTPS POST
要求傳送至 Google 的授權伺服器 (https://oauth2.googleapis.com/token
),其中包含下列參數:
欄位 | |
---|---|
client_id |
從 API Console取得的用戶端 ID。 |
client_secret |
從 API Console取得的用戶端密鑰。
(client_secret 不適用於註冊為 Android、iOS 或 Chrome 應用程式的用戶端發出的要求)。
|
grant_type |
根據 OAuth 2.0 規格定義,這個欄位的值必須設為 refresh_token 。 |
refresh_token |
交換授權碼時傳回的更新權杖。 |
以下程式碼片段為要求範例:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
只要使用者尚未撤銷授予應用程式的存取權,憑證伺服器就會傳回包含新存取權杖的 JSON 物件。下列程式碼片段顯示回應範例:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly", "token_type": "Bearer" }
請注意,發送的更新權杖有數量限制;每個用戶端/使用者組合各有一個限制,而所有用戶端上每位使用者只能有一項限制。您應該長期將更新權杖儲存在長期儲存空間中,並在權杖有效期間繼續使用。如果您的應用程式要求的更新權杖過多,可能會超過這些限制,屆時舊的更新權杖會停止運作。
撤銷權杖
在某些情況下,使用者可能會想撤銷應用程式的存取權。使用者可以前往「 帳戶設定」撤銷存取權。詳情請參閱「針對具有您帳戶存取權的第三方網站和應用程式存取權」支援文件。
應用程式也可能會透過程式輔助方式撤銷存取權。若是使用者取消訂閱、移除應用程式,或者應用程式所需 API 資源已大幅變更,程式輔助撤銷就相當重要。也就是說,移除程序的部分內容可能包含 API 要求,確保先前授予應用程式的權限均已移除。
如要透過程式撤銷權杖,應用程式會向 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
,以及錯誤代碼。
延伸閱讀
網際網路工程任務組 (IETF) 現行最佳做法「原生應用程式專用 OAuth 2.0」建立了本文所述的許多最佳做法。