行動與電腦版應用程式的 OAuth 2.0

注意：如果您是 OAuth 2.0 的新手，建議您先閱讀 開始前，請先參閱 OAuth 2.0 總覽。 總覽介紹 Google 支援的 OAuth 2.0 流程 您已為應用程式選取適當的流程。

本文件說明在手機、平板電腦及 電腦會使用 Google 的 OAuth 2.0 端點 Google API

OAuth 2.0 可讓使用者與應用程式共用特定資料，同時維持 使用者名稱、密碼以及其他資訊隱私 舉例來說，應用程式可以使用 OAuth 2.0 取得 讓使用者在 Google 雲端硬碟中儲存檔案。

已安裝的應用程式會發布至個別裝置，假設這些應用程式已不適用 不能保存秘密即便使用者正在使用應用程式，應用程式也能存取 Google API。 應用程式正在背景執行。

這個授權流程與 網路伺服器應用程式主要差別在於 已安裝的應用程式必須開啟系統瀏覽器，並提供本機重新導向 URI 來處理 回應。

替代方案

如果是行動應用程式，建議您使用 Google 登入 Android 或 iOS：Google 登入 用戶端程式庫可處理驗證與使用者授權作業， 實作這裡提到的 較低層級的通訊協定

應用程式在不支援系統瀏覽器，或輸入來源有限的裝置中執行 功能，例如電視、遊戲主機、攝影機或印表機 電視和電視適用的 OAuth 2.0裝置 或在電視上和受限制的輸入裝置登入帳戶。

程式庫與範例

建議您使用下列程式庫和範例，以便導入 OAuth 2.0 流程 中所述的程序：

• AppAuth for Android 程式庫
• AppAuth for iOS 程式庫
• 應用程式的 OAuth：Windows 範例

必要條件

為專案啟用 API

凡是呼叫 Google API 的應用程式，都必須在 API Console。

如何在專案中啟用 API：

1. Open the API Library 內 Google API Console。
2. If prompted, select a project, or create a new one.
3. API Library 會列出所有可用的 API，並按照產品分組 家庭及熱門程度如果清單裡找不到您想啟用的 API，請使用搜尋功能 找到所需產品，或是在所屬的產品系列中按一下 [查看全部]。
4. 選取要啟用的 API，然後按一下「Enable」按鈕。
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

建立授權憑證

凡是使用 OAuth 2.0 存取 Google API 的應用程式，都必須具備授權憑證 可與 Google 的 OAuth 2.0 伺服器識別應用程式。下列步驟說明如何 為專案建立憑證接著，您的應用程式即可使用憑證存取 API 找出您已啟用的專案

1. Go to the Credentials page.
2. 按一下 [Create credentials] (建立憑證) > [OAuth client ID] (OAuth 用戶端 ID)。
3. 以下各節將說明用戶端類型和 Google 的重新導向方法 授權伺服器支援。選擇適合您的用戶端類型 為 OAuth 用戶端命名，然後將其他欄位設為 或適當。

Android

1. 選取「Android」Android應用程式類型。
2. 輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的 Credentials page 用於識別用戶端。
3. 輸入 Android 應用程式的套件名稱。這個值是在 <manifest> 元素的 package 屬性 。
4. 請輸入應用程式發布版本的 SHA-1 簽署憑證指紋。
   • 如果應用程式使用 擷取指紋。
   • 如果您自行管理 KeyStore 和簽署金鑰，請使用 keytool 公用程式 。複製 在以下應用程式的 Certificate fingerprints 區段中的 SHA1 值： keytool 輸出內容。詳情請見 驗證用戶端 詳情請參閱適用於 Android 的 Google API 說明文件。
5. (選用) 驗證您的 Android 裝置擁有權 應用程式。
6. 按一下「建立」。

iOS

1. 選取「iOS」iOS應用程式類型。
2. 輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的 Credentials page 用於識別用戶端。
3. 輸入應用程式的軟體包 ID。軟體包 ID 是指 CFBundleIdentifier 鍵的值 (info.plist)。這個鍵 最常顯示在 [General] 窗格中，「功能」窗格 Xcode 專案編輯器這個軟體包 ID 也會顯示在 前往應用程式的「應用程式資訊」頁面 Apple 的 App Store Connect 網站。
4. (選填)？

   如果該應用程式是在 Apple 的 App Store 中發布，請輸入應用程式的 App Store ID。商店 ID 為 一個數字字串。

   1. 開啟 Apple App Store 應用程式 在您的 iOS 或 iPadOS 裝置上。
   2. 搜尋您的應用程式。
   3. 選取「分享」按鈕 (方形和向上箭頭)。
   4. 選取「複製連結」。
   5. 將連結貼到文字編輯器中。網址的最終部分即為 App Store ID。

      範例：https://apps.apple.com/app/google/id284815942

5. (選填)？

   請輸入團隊 ID。詳情請見 找出你的團隊 ID 。

6. 按一下「建立」。

UWP

1. 選取「Universal Windows Platform」應用程式類型。
2. 輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的 Credentials page 用於識別用戶端。
3. 輸入應用程式的 Microsoft Store ID (最多 12 個字元)。您可以在 Microsoft 合作夥伴中心 的 應用程式識別 頁面。
4. 按一下「建立」。

UWP 應用程式的自訂 URI 配置長度不得超過 39 個字元。

自訂 URI 配置 (Android、iOS、UWP)

自訂 URI 配置是一種深層連結，可使用自訂的配置開啟應用程式。

重要事項：新的 Chrome 應用程式已不再支援自訂 URI 配置， 因為應用程式冒用風險，新的 Android 用戶端會預設為停用。

，瞭解如何調查及移除這項存取權。 在 Android 上使用自訂 URI 配置的替代方案

使用 Android SDK 適用的 Google 登入 將 OAuth 2.0 回應直接傳送至您的應用程式，無需使用 重新導向 URI

如何改用 Android 版 Google 登入 SDK

如果您目前為 Android 上的 OAuth 整合採用自訂配置，您將需要 請完成下列操作，全面改用 Android SDK：

1. 請更新程式碼以使用 Google 登入 SDK。
2. 停止在 Google API 控制台中支援自訂配置。

，瞭解如何調查及移除這項存取權。

注意：請務必完成並部署程式碼更新 (將採用時間納入考量) ，再停用現有配置對自訂配置的支援 Google API 控制台，避免使用者收到 invalid_request 則錯誤訊息 適時適地向他們顯示廣告

請按照下列步驟遷移至 Google 登入 Android SDK：

1. 更新程式碼即可使用 Google 登入 Android SDK：
   1. 檢查程式碼來確認所在位置 傳送要求至 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 是 。詳情請參閱 redirect_uri 參數定義，進一步瞭解格式 自訂 URI 配置值的請求
   2. 記下 scope 和 client_id 要求參數，以便用於 請設定 Google 登入 SDK
      注意：如果您使用第三方程式庫，請參閱程式庫的 設定檔，即可找到這些資訊。
   3. 跟著 開始將 Google 登入整合至 Android 應用程式 設定 SDK 的操作說明。您可以略過 取得後端伺服器的 OAuth 2.0 用戶端 ID 步驟，與重複使用時相同 您在上一個步驟中擷取的 client_id。
   4. 跟著 啟用伺服器端 API 存取權 操作說明。其中包含下列步驟：
      1. 請使用 getServerAuthCode 方法擷取 您需要的權限範圍
      2. 將驗證碼傳送至應用程式的後端，用來交換存取權，重新整理 產生下一個符記
      3. 使用擷取的存取權杖，代表使用者呼叫 Google API。
      ，瞭解如何調查及移除這項存取權。
      注意：如果您的應用程式不需要離線存取，請按照 這些操作說明，改為要求用戶端 API 存取權。
2. 停止在 Google API 控制台中支援自訂配置：
   1. 前往 OAuth 2.0 憑證 清單並選取您的 Android 用戶端。
   2. 前往「進階設定」部分，取消勾選 「Enable Custom URI Scheme」核取方塊，並按一下「Save」 停用自訂 URI 配置支援。

啟用自訂 URI 配置

如果建議的替代方案不適用於您的情況，您可以啟用自訂 URI 配置的 Android 用戶端的步驟如下：

1. 前往 OAuth 2.0 憑證清單和 選取您的 Android 用戶端。
2. 前往「進階設定」部分查看 「Enable Custom URI Scheme」核取方塊，然後按一下「Save」啟用。 自訂 URI 配置支援。

，瞭解如何調查及移除這項存取權。 在 Chrome 應用程式使用自訂 URI 配置的替代方案

使用 Chrome Identity API 將 OAuth 2.0 回應直接傳送至您的應用程式，無需使用 重新導向 URI

驗證應用程式擁有權 (Android、Chrome)

您可以驗證應用程式的擁有權，降低應用程式冒用身分的風險。

Android

注意：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 擴充功能 OAuth 用戶端相同 驗證狀態
• 您必須是 Chrome 線上應用程式商店商品的發布者。 瞭解詳情 關於 Chrome 線上應用程式商店開發人員資訊主頁的存取權管理功能。

在 Chrome 擴充功能用戶端的「驗證應用程式擁有權」部分中，按一下 點按「驗證擁有權」按鈕即可完成驗證程序。

注意：請等待幾分鐘，完成後再完成驗證程序 授與帳戶存取權。

如果驗證成功，系統會顯示通知確認驗證成功 驗證流程否則，系統會顯示錯誤提示。

如要修正驗證失敗的問題，請按照下列步驟操作：

• 請確實在 Chrome 線上應用程式商店開發人員資訊主頁中， 項目 ID，必須與您要完成驗證程序的 Chrome 擴充功能 OAuth 用戶端相同。
• 確認您是應用程式的發布者，也就是說您必須是個別發布者 應用程式或群組發布者的成員。 瞭解詳情 關於 Chrome 線上應用程式商店開發人員資訊主頁的存取權管理功能。
• 如果您不久前才更新群組發布者清單，請確認群組發布者是否符合資格 清單會同步在 Chrome 線上應用程式商店開發人員資訊主頁。 瞭解詳情 瞭解如何同步處理發布者會員名單

回送 IP 位址 (macOS、Linux、Windows 桌面)

重要事項：回送 IP 位址重新導向選項為 已於 Android、Chrome 應用程式和 iOS OAuth 用戶端類型淘汰。 查看循環 IP 地址遷移指南，瞭解如何遷移至支援的替代方案。

若要使用這個網址接收授權碼，您的應用程式必須監聽 本機網路伺服器適用範圍不多，但並非所有平台都適用。不過，如果您使用平台 支援，建議您使用這個方法取得授權碼。

應用程式收到授權回應後，為確保可用性，您應在下列期限之前回應： 顯示 HTML 網頁，指示使用者關閉瀏覽器並返回應用程式。

建議用量	macOS、Linux 和 Windows 桌面 (但非通用 Windows 平台) 應用程式
表單值	將應用程式類型設為「電腦版應用程式」。

注意：請參閱 redirect_uri 參數定義： 進一步瞭解回送 IP 位址。您也可以使用 localhost 是回送 IP，但這項設定可能會導致 用戶端防火牆。大多數 (但非全部) 防火牆允許回送通訊。

手動複製/貼上

重要事項：手動複製/貼上選項也稱為 的外界點 (OOB) 重新導向方法， 已不支援。 參閱 OOB 遷移指南 ，瞭解如何改用安全的替代方法。

識別存取權範圍

限定範圍可讓應用程式只要求存取其所需資源， 讓使用者控制他們授予應用程式的存取權限量。因此， 可能是要求的範圍數量與 徵得使用者同意

建議您先確定執行 OAuth 2.0 授權的範圍後，再開始執行 OAuth 2.0 授權 才能存取您的應用程式

注意：漸進式授權不適用於已安裝的應用程式或 裝置。

OAuth 2.0 API 範圍文件提供了 列出可能用於存取 Google API 的範圍清單。

如果您的公開應用程式使用的範圍允許存取 就必須完成驗證程序。如果看到「未驗證」 測試應用程式時，務必提交 驗證要求加以移除進一步瞭解 未驗證的應用程式 並取得「」的答案 有關應用程式驗證的常見問題，

取得 OAuth 2.0 存取權杖

下列步驟顯示應用程式如何與 Google 的 OAuth 2.0 伺服器互動，以取得 使用者同意代為執行 API 要求。您的應用程式必須符合下列條件 才能執行需要使用者授權的 Google API 要求。

步驟 1：產生程式碼驗證器和驗證問題

Google 支援程式碼交換金鑰證明 (PKCE) 通訊協定，讓已安裝的應用程式流程更加安全。系統會為 授權要求及其轉換值「code_challenge」會傳送到 取得授權碼。

建立程式碼驗證器

code_verifier 是使用未保留的高熵加密編譯字串 字元 [A-Z] / [a-z] / [0-9] /「-」。」/「_」/ "~"，長度至少 43 個字元 長度上限為 128 個半形字元

程式碼驗證器應有足夠的熵，以致於無法猜測值。

建立代碼挑戰

系統支援兩種建立程式碼驗證方式的方法。

程式碼驗證產生方法
S256 (建議)	程式碼驗證問題是採用 Base64URL (不含填充字元) 編碼的程式碼 SHA256 雜湊 驗證器。 code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
純白	程式碼驗證器的值與上方產生的程式碼驗證器相同。 code_challenge = code_verifier

步驟 2：將要求傳送到 Google 的 OAuth 2.0 伺服器

如要取得使用者授權，請傳送要求至 Google 的授權伺服器： https://accounts.google.com/o/oauth2/v2/auth。這個端點會處理運作中的工作階段查詢， 驗證使用者並取得使用者同意。端點只能透過 SSL 存取 拒絕 HTTP (非 SSL) 連線。

授權伺服器支援下列已安裝的查詢字串參數 應用程式：

參數
client_id	必填 應用程式的用戶端 ID。您可以在 API Console Credentials page。
redirect_uri	必填 決定 Google 的授權伺服器向應用程式傳送回應的方式。另有 已安裝應用程式可以使用的幾個重新導向選項，您將在 使用特定重新導向方法的授權憑證 這個值必須與其中一個授權的 OAuth 2.0 重新導向 URI 完全相符 您在客戶的 API Console Credentials page。如果這個值與 授權 URI 時，您會收到 redirect_uri_mismatch 錯誤。 下表顯示了以下項目的適當 redirect_uri 參數值： 每個方法的用詞是： redirect_uri 個值 自訂 URI 配置 com.example.app:redirect_uri_path 或 com.googleusercontent.apps.123:redirect_uri_path com.example.app 是群組中網域的反向 DNS 標記法 掌控權自訂配置必須包含一個句號，才算有效。 com.googleusercontent.apps.123 是 用戶端 ID。 redirect_uri_path 是選用的路徑元件，例如 /oauth2redirect。請注意，路徑的開頭必須是 和一般 HTTP 網址不同 ，瞭解如何調查及移除這項存取權。 注意：Chrome 應用程式和 在 Android 上預設為停用 瞭解詳情 瞭解 Android 和 Chrome 應用程式的自訂配置替代方案。 回送 IP 位址 http://127.0.0.1:port或 http://[::1]:port 向平台查詢相關的回送 IP 位址，並啟動 HTTP 來自隨機可用的通訊埠的接聽程式。將 port 替換成實際值 通訊埠號碼。 請注意，行動裝置支援回送 IP 位址重新導向選項 應用程式 是 已淘汰。
response_type	必填 決定 Google OAuth 2.0 端點是否傳回授權碼。 如果是已安裝的應用程式，請將參數值設為 code。
scope	必填 A 罩杯 以空格分隔 這些範圍清單會指出應用程式可在 代表使用者這些值決定 Google 向 內容。 限定範圍可讓應用程式只要求存取其所需資源 並讓使用者控制授予 應用程式。因此，要求的範圍數量之間存在反向關係 以及取得使用者同意聲明的可能性
code_challenge	建議事項 指定用於做為伺服器端的編碼 code_verifier 驗證驗證碼詳情請見 建立程式碼 挑戰一節。
code_challenge_method	建議事項 指定用於將 code_verifier 編碼的方法 產生憑證這個參數必須與 code_challenge 參數。code_challenge_method 的值 如果要求中沒有包含 plain code_challenge。這個參數唯一支援的值是 S256 或 plain。
state	建議事項 指定應用程式用來維持 授權要求和授權伺服器的回應。 伺服器會傳回您以 name=value 組合形式傳送的確切值， 網址片段 ID (#) 的 redirect_uri使用者同意或拒絕應用程式的 存取要求。 這個參數可用於多種用途，例如將使用者導向 在應用程式中使用正確的資源、傳送 Nonce 以及降低跨網站要求 偽造。由於您可以猜測 redirect_uri，因此使用 state 值可讓您確保傳入連線的結果是 驗證要求如果您產生隨機字串或將 Cookie 雜湊編碼 另一個會擷取用戶端狀態的值，您可以驗證 也要確保請求和回應都來自相同的瀏覽器。 提供網路攻擊防護功能 跨網站要求 偽造。詳情請參閱 OpenID Connect 範例，說明如何建立並確認 state 權杖。 重要事項：OAuth 用戶端必須防止 CSRF，如 OAuth2 規格 。而其中一種方法是使用 state 參數， 狀態，
login_hint	選用 如果應用程式知道哪個使用者想要進行驗證，則可以使用此參數 為 Google 驗證伺服器提供提示伺服器會利用提示 透過在登入表單中預先填入電子郵件欄位，或 選取適當的多帳戶登入工作階段 將參數值設為電子郵件地址或 sub ID ( 會對應至使用者的 Google ID

注意：系統不支援對已安裝的應用程式進行漸進式授權，， 事實上，用戶端不能將client_secret保密。

授權網址範例

下列分頁顯示不同重新導向 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 帳戶無法授權一或多個要求的範圍 Google Workspace 管理員參閱 Google Workspace 管理員說明文章 控管哪些第三方和內部應用程式存取 Google Workspace 資料 進一步瞭解管理員可能如何限制所有範圍或敏感資料的存取權，以及 受到限制，直到已明確授予 OAuth 用戶端 ID 存取權為止。

disallowed_useragent

授權端點會顯示在 Google 的 OAuth 2.0 政策。

Android

Android 開發人員在 android.webkit.WebView。 開發人員應改用 Android 程式庫，例如 Android 版 Google 登入或 OpenID Foundation 的 AppAuth for Android：

當 Android 應用程式在 內嵌使用者代理程式，而使用者前往 Google 的 OAuth 2.0 授權端點 你的網站開發人員應允許使用預設連結處理常式開啟一般連結， 其中包括 Android 應用程式連結 處理常式或預設的瀏覽器應用程式中。 Android 自訂分頁 另一個支援選項

iOS

iOS 和 macOS 開發人員在 WKWebView。 開發人員應改用 iOS 程式庫，例如 iOS 版 Google 登入或 OpenID Foundation 的 AppAuth for iOS：

當 iOS 或 macOS 應用程式在 內嵌使用者代理程式，然後使用者透過 你的網站開發人員應允許使用預設連結處理常式開啟一般連結， 其中包括 通用連結 處理常式或預設的瀏覽器應用程式中。 SFSafariViewController 另一個支援選項

org_internal

請求中的 OAuth 用戶端 ID 所屬的專案，限制了 Google 帳戶存取 特定 Google Cloud 機構。 如要進一步瞭解這個設定選項，請參閱 使用者類型 部分。

invalid_grant

如果您使用 程式碼驗證器和 挑戰，code_callenge 參數無效或遺失。請確認 code_challenge 參數設定正確。

重新整理存取權杖時，該權杖可能已過期或 已失效。 再次驗證使用者，並要求使用者同意取得新的權杖。如果您選擇繼續 看到這則錯誤訊息，請確認您的應用程式設定正確， 要求使用正確的符記和參數否則，使用者帳戶 可能已遭刪除或停用

redirect_uri_mismatch

授權要求中傳遞的 redirect_uri 與已授權要求不符 OAuth 用戶端 ID 的重新導向 URI。查看 Google API Console Credentials page。

傳遞的 redirect_uri 可能不適用於用戶端類型。

redirect_uri 參數可能是指 OAuth 的架構外 (OOB) 流程， 已淘汰，不再受到支援。詳情請參閱 遷移指南，以更新 擷取及準備資料、針對特定領域進行預先訓練 調整指示、離線評估和整合

invalid_request

您提出的要求發生問題。可能原因如下：

• 要求的格式不正確
• 要求中缺少必要參數
• 這項要求使用了 Google 不支援的授權方法。驗證 OAuth 整合採用建議的整合方式
• 用於重新導向 URI 的自訂配置：如果看到錯誤訊息 Chrome 應用程式或自訂 URI 配置不支援自訂 URI 配置 未為您的 Android 用戶端啟用，表示您使用的是自訂 URI Chrome 應用程式不支援且預設為停用的配置 Android。進一步瞭解自訂 URI 配置 替代方案

步驟 4：處理 OAuth 2.0 伺服器回應

應用程式收到授權回應的方式取決於 重新導向 URI 配置。無論配置為何 回應將包含授權碼 (code) 或錯誤 (error).舉例來說，error=access_denied 表示 拒絕要求。

如果使用者授予應用程式存取權，您就可以交換 存取權杖和更新權杖，如下個步驟所述。

步驟 5：交換用於重新整理及存取的授權碼 權杖

如要用授權碼交換存取權杖，請呼叫 https://oauth2.googleapis.com/token 端點並設定下列參數：

欄位
client_id	從 API Console取得的用戶端 ID Credentials page。
client_secret	從 API Console取得的用戶端密鑰 Credentials page。
code	初始要求傳回的授權碼。
code_verifier	您在 Cloud Shell 建立的程式碼驗證器 步驟 1：
grant_type	根據 OAuth 2.0 中的定義 規格，這個欄位的值必須設為 authorization_code。
redirect_uri	在 API Console Credentials page 已提供 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=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。

重要事項：您的應用程式應將這兩個權杖儲存在安全的、 能在應用程式的不同叫用之間存取的長效位置。 更新憑證可讓您的應用程式取得新的存取權杖 (如果有的話) 過期。因此，如果應用程式遺失更新權杖，使用者就必須重複執行 OAuth 2.0 同意流程後，應用程式才能取得新的更新權杖。

以下程式碼片段為回應範例：

{
  "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

應用程式取得存取權杖後，您可以使用該權杖向 Google 代表指定的 使用者帳戶。方法是加入 加入 access_token 查詢，藉此將存取權杖用於傳送至 API 的要求中 參數或 Authorization HTTP 標頭 Bearer 值。可能的話 HTTP 標頭較為理想，因為這類字串通常會顯示在伺服器記錄中。大多數 使用用戶端程式庫來設定對 Google API 的呼叫 (例如，在 呼叫 Drive Files API)。

您可以試用所有 Google API 並查看相關範圍： OAuth 2.0 Playground。

HTTP GET 範例

對 drive.files 端點 (Drive Files API)Authorization: BearerHTTP 標題可能如下所示。請注意，您必須指定自己的存取權杖：

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 資源大幅變更。也就是 移除程序中的某個部分可包含 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 原生應用程式建立了許多本文所述的最佳做法。