本頁面由 Cloud Translation API 翻譯而成。

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

本文說明如何在手機、平板電腦和電腦等裝置上安裝應用程式，使用 Google OAuth 2.0 端點授權存取 YouTube Data API。

OAuth 2.0 可讓使用者與應用程式共用特定資料，同時保有使用者名稱、密碼和其他資訊的隱私。舉例來說，應用程式可以使用 OAuth 2.0 取得權限，以便擷取頻道的 YouTube 資料。

已安裝的應用程式會分發至個別裝置，且這些應用程式無法保留機密資料。使用者在應用程式中，或應用程式在背景執行時，都可以存取 Google API。

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

替代方案

如果是行動應用程式，建議您使用 Android 或 iOS 版的 Google 登入功能。Google 登入用戶端程式庫會處理驗證和使用者授權作業，而且可能比這裡所述的低階通訊協定更容易導入。

如果應用程式在裝置上執行，但該裝置不支援系統瀏覽器或輸入功能受限 (例如電視、遊戲主機、相機或印表機)，請參閱適用於電視和裝置的 OAuth 2.0 或在電視和輸入功能受限的裝置上登入。

程式庫與範例

建議您使用下列程式庫和範例，實作本文所述的 OAuth 2.0 流程：

必要條件

為專案啟用 API

任何會呼叫 Google API 的應用程式，都必須在中啟用這些 API。

如要為專案啟用 API，請按照下列步驟操作：

在中。
請使用「程式庫」頁面找出並啟用 YouTube Data API。找出應用程式將使用的任何其他 API，並啟用這些 API。

建立授權憑證

任何使用 OAuth 2.0 存取 Google API 的應用程式，都必須具備授權憑證，才能向 Google 的 OAuth 2.0 伺服器識別應用程式。下列步驟說明如何為專案建立憑證。應用程式就能使用憑證存取您為該專案啟用的 API。

按一下 [Create credentials] (建立憑證) > [OAuth client ID] (OAuth 用戶端 ID)。
以下各節說明 Google 授權伺服器支援的用戶端類型。請選擇應用程式建議的用戶端類型、為 OAuth 用戶端命名，並視需要設定表單中的其他欄位。

Android

選取「Android」應用程式類型。
輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的上，用於識別用戶端。
輸入 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 用戶端的名稱。這個名稱會顯示在專案的上，用於識別用戶端。
輸入應用程式的軟體包 ID。軟體包 ID 是應用程式資訊屬性清單資源檔案 (info.plist) 中 CFBundleIdentifier 鍵的值。這個值通常會顯示在 Xcode 專案編輯器的「General」窗格或「Signing & Capabilities」窗格中。在 Apple 的 App Store Connect 網站上，應用程式「應用程式資訊」頁面的「一般資訊」部分也會顯示套件 ID。
請確認您為應用程式使用的軟體包 ID 正確無誤，因為如果您使用 App Check 功能，就無法變更該 ID。
(選用)
如果應用程式已在 Apple App Store 中發布，請輸入應用程式的 App Store ID。商店 ID 是每個 Apple App Store 網址中包含的數字字串。
1. 在 iOS 或 iPadOS 裝置上開啟 Apple App Store 應用程式。
2. 搜尋您的應用程式。
3. 選取「分享」按鈕 (方塊和向上箭頭圖示)。
4. 選取「複製連結」。
5. 將連結貼到文字編輯器中。App Store ID 是網址的最後一部分。
  範例：https://apps.apple.com/app/google/id284815942
(選用)
輸入您的團隊 ID。詳情請參閱 Apple Developer Account 說明文件中的「找出團隊 ID」。
注意：如果您要為用戶端啟用 App Check，則必須填寫「Team ID」欄位。
(選用)
為 iOS 應用程式啟用 App Check。啟用 App Check 後，Apple 的 App Attest 服務就會用於驗證來自 OAuth 用戶端的 OAuth 2.0 要求是否為真，並來自您的應用程式。這有助於降低應用程式冒用風險。進一步瞭解如何為 iOS 應用程式啟用 App Check。
按一下「建立」。

UWP

選取「通用 Windows 平台」應用程式類型。
輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的上，用於識別用戶端。
輸入應用程式的 12 個字元 Microsoft Store ID。您可以在 Microsoft Partner Center 的「應用程式管理」部分，找到「應用程式身分」頁面中的這個值。
按一下「建立」。

對於 UWP 應用程式，自訂 URI 配置不得超過 39 個半形字元。

找出存取權範圍

範圍可讓應用程式僅要求存取其需要的資源，也能讓使用者控制對應用程式授予的存取量。因此，要求的範圍數量與取得使用者同意的可能性之間可能呈現反比關係。

開始實作 OAuth 2.0 授權之前，建議您找出應用程式需要權限存取的範圍。

YouTube Data API v3 會使用下列範圍：

狙擊鏡
https://www.googleapis.com/auth/youtube	管理您的 YouTube 帳戶
https://www.googleapis.com/auth/youtube.channel-memberships.creator	查看您現有的有效頻道會員清單，以及這些會員目前的級別和成為會員的時間點
https://www.googleapis.com/auth/youtube.force-ssl	查看、編輯並永久刪除您的 YouTube 影片、評分、留言和字幕
https://www.googleapis.com/auth/youtube.readonly	查看您的 YouTube 帳戶
https://www.googleapis.com/auth/youtube.upload	管理您的 YouTube 影片
https://www.googleapis.com/auth/youtubepartner	查看及管理您在 YouTube 上的元素和相關內容
https://www.googleapis.com/auth/youtubepartner-channel-audit	查看您的 YouTube 頻道中與 YouTube 合作夥伴稽核程序相關的私人資訊

「OAuth 2.0 API 範圍」文件包含您可能用於存取 Google API 的範圍完整清單。

取得 OAuth 2.0 存取權杖

以下步驟說明應用程式如何與 Google 的 OAuth 2.0 伺服器互動，取得使用者同意，代表使用者執行 API 要求。應用程式必須取得同意聲明，才能執行需要使用者授權的 Google API 要求。

步驟 1：產生驗證碼和驗證碼挑戰

Google 支援 Proof Key for Code Exchange (PKCE) 通訊協定，讓安裝應用程式流程更加安全。系統會為每個授權要求建立專屬的代碼驗證器，並將其轉換值 (稱為「code_challenge」) 傳送至授權伺服器，以取得授權碼。

建立程式碼驗證器

code_verifier 是使用未保留字元 [A-Z] / [a-z] / [0-9] /「-」/「.」/「_」/「~」的高熵加密隨機字串，長度最短為 43 個字元，最長為 128 個字元。

程式碼驗證器應具備足夠的熵，讓值無法被猜測。

建立驗證碼問題

系統支援兩種建立程式碼挑戰的方法。

程式碼挑戰產生方法
S256 (建議選項)	程式碼挑戰是程式碼驗證工具的 Base64URL (不含填充) 編碼 SHA256 雜湊。 `code_challenge` = BASE64URL-ENCODE(SHA256(ASCII(`code_verifier`)))
plain	程式碼挑戰與上述產生的程式碼驗證器相同。 `code_challenge` = `code_verifier`

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

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

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

參數

client_id

必填

應用程式的用戶端 ID。您可以在中找到這個值。

redirect_uri

必填：

決定 Google 授權伺服器如何向您的應用程式傳送回應。已安裝的應用程式可使用多種重新導向選項，您可以根據特定重新導向方法設定授權憑證。

這個值必須與 OAuth 2.0 用戶端的授權重新導向 URI 完全相符，您可以在用戶端的中設定這項值。如果這個值與授權的 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 的反向 DNS 符號。
redirect_uri_path 是選用路徑元件，例如 /oauth2redirect。請注意，路徑應以單斜線開頭，這與一般 HTTP 網址不同。

回送 IP 位址

http://127.0.0.1:port 或 http://[::1]:port

請查詢平台的相關迴圈 IP 位址，並在隨機可用連接埠上啟動 HTTP 監聽器。將 port 替換成應用程式監聽的實際通訊埠編號。

請注意，行動應用程式的回送 IP 位址重新導向選項已已淘汰。

response_type

必填：

判斷 Google OAuth 2.0 端點是否會傳回授權碼。

將參數值設為已安裝應用程式的 code。

scope

必填

以空格分隔的範圍清單，用於識別應用程式可代表使用者存取的資源。這些值會提供 Google 向使用者顯示的同意畫面。

範圍可讓應用程式僅要求存取其需要的資源，也能讓使用者控制對應用程式授予的存取量。因此，要求的範圍數量與取得使用者同意的可能性之間存在反比關係。

YouTube Data API v3 會使用下列範圍：

狙擊鏡
https://www.googleapis.com/auth/youtube	管理您的 YouTube 帳戶
https://www.googleapis.com/auth/youtube.channel-memberships.creator	查看您現有的有效頻道會員清單，以及這些會員目前的級別和成為會員的時間點
https://www.googleapis.com/auth/youtube.force-ssl	查看、編輯並永久刪除您的 YouTube 影片、評分、留言和字幕
https://www.googleapis.com/auth/youtube.readonly	查看您的 YouTube 帳戶
https://www.googleapis.com/auth/youtube.upload	管理您的 YouTube 影片
https://www.googleapis.com/auth/youtubepartner	查看及管理您在 YouTube 上的元素和相關內容
https://www.googleapis.com/auth/youtubepartner-channel-audit	查看您的 YouTube 頻道中與 YouTube 合作夥伴稽核程序相關的私人資訊

「OAuth 2.0 API 範圍」文件提供您可能用於存取 Google API 的範圍完整清單。

code_challenge

建議

指定在授權碼交換期間，用於做為伺服器端挑戰的編碼 code_verifier。詳情請參閱上方的「建立程式碼挑戰」一節。

code_challenge_method

建議

指定用於編碼 code_verifier 的方法，該方法會在授權碼交換期間使用。這個參數必須搭配上述的 code_challenge 參數使用。如果 code_challenge_method 的值不在包含 code_challenge 的要求中，則預設為 plain。這個參數僅支援 S256 或 plain 的值。

state

建議

指定應用程式用於在授權要求和授權伺服器回應之間維持狀態的任何字串值。在使用者同意或拒絕應用程式的存取要求後，伺服器會傳回您在 redirect_uri 的網址片段 ID (#) 中，以 name=value 成對傳送的確切值。

您可以將這個參數用於多種用途，例如將使用者導向應用程式中的正確資源、傳送 Nonce，以及減輕跨網站請求偽造問題。由於 redirect_uri 可能會遭到猜測，因此使用 state 值可提高您對傳入連線的信心，確保該連線是驗證要求的結果。如果您產生隨機字串，或對擷取用戶端狀態的 Cookie 或其他值進行雜湊編碼，您可以驗證回應，進一步確保要求和回應來自同一個瀏覽器，以防範跨網站要求偽造等攻擊。如需建立及確認 state 權杖的範例，請參閱 OpenID Connect 說明文件。

重要事項：OAuth 用戶端必須防範 OAuth2 規格中提及的 CSRF。達成這項目標的方法之一，是使用 state 參數在授權要求和授權伺服器回應之間維持狀態。

login_hint

選填：

如果應用程式知道哪位使用者嘗試進行驗證，可以使用這個參數向 Google 驗證伺服器提供提示。伺服器會使用提示簡化登入流程，方法是預先填入登入表單中的電子郵件欄位，或選取適當的多重登入工作階段。

將參數值設為電子郵件地址或 sub ID，這與使用者的 Google ID 相同。

注意：由於用戶端無法保密 client_secret，因此系統不支援使用已安裝應用程式進行遞增授權。

授權網址範例

下方分頁會顯示不同重新導向 URI 選項的授權網址範例。

每個網址都會要求存取範圍，允許存取權以便擷取使用者的 YouTube 資料。

除了 redirect_uri 參數的值不同，其他部分的網址都相同。網址也包含必要的 response_type 和 client_id 參數，以及選用的 state 參數。每個網址都包含換行符號和空格，方便閱讀。

自訂 URI 配置

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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 帳戶無法授權所要求的一或多個範圍。如要進一步瞭解管理員如何限制對所有範圍或機密和受限制範圍的存取權，直到明確授予 OAuth 客戶端 ID 存取權為止，請參閱 Google Workspace 管理員說明文章「控管哪些第三方應用程式和內部應用程式可存取 Google Workspace 資料」。

`disallowed_useragent`

授權端點會顯示在 Google 的 OAuth 2.0 政策禁止使用的嵌入式使用者代理程式中。

Android

Android 開發人員在 android.webkit.WebView 中開啟授權要求時，可能會遇到這則錯誤訊息。開發人員應改用 Android 程式庫，例如 Google 登入 (Android 版) 或 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_grant`

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

更新存取權杖時，權杖可能已過期或已失效。再次驗證使用者身分，並徵求使用者同意取得新的權杖。如果您持續看到這項錯誤，請確認應用程式已正確設定，且您在要求中使用正確的符記和參數。否則，使用者帳戶可能已遭到刪除或停用。

`redirect_uri_mismatch`

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

傳遞的 redirect_uri 可能對用戶端類型無效。

redirect_uri 參數可能會參照已淘汰且不再支援的 OAuth 額外管道 (OOB) 流程。請參閱遷移指南更新整合功能。

`invalid_request`

您提出的要求發生錯誤，這可能是由多種原因造成：

要求格式不正確
要求缺少必要參數
要求使用 Google 不支援的授權方法。確認 OAuth 整合功能使用建議的整合方法
重新導向 URI 使用自訂配置：如果您看到「Chrome 應用程式不支援自訂 URI 配置」或「Android 用戶端未啟用自訂 URI 配置」錯誤訊息，表示您使用的自訂 URI 配置在 Chrome 應用程式中不受支援，且預設情況下在 Android 中會停用。進一步瞭解自訂 URI 配置的替代方案

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

應用程式接收授權回應的方式取決於所使用的重新導向 URI 配置。無論是哪種配置，回應都會包含授權碼 (code) 或錯誤 (error)。例如，error=access_denied 表示使用者拒絕要求。

如果使用者授予應用程式存取權，您可以按照下一個步驟的說明，將授權碼換成存取權杖和更新權杖。

步驟 5：交換授權碼，取得更新和存取權杖

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

欄位
`client_id`	從取得的用戶端 ID。
`client_secret`	從取得的用戶端密鑰。
`code`	初始要求傳回的授權碼。
`code_verifier`	您在步驟 1 中建立的程式碼驗證器。
`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=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/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

步驟 6：檢查使用者授予的範圍

一次要求多個權限範圍時，使用者可能不會授予應用程式要求的所有權限範圍。應用程式應一律檢查使用者授予的存取範圍，並透過停用相關功能來處理任何存取範圍拒絕的情況。詳情請參閱如何處理精細權限。

如要檢查使用者是否已授予應用程式存取特定範圍的權限，請查看存取權存取金鑰回應中的 scope 欄位。由 access_token 授予的存取權範圍，以空格分隔的字串清單表示，並區分大小寫。

舉例來說，下列存取權存取權杖回應範例指出，使用者已授予應用程式存取權，可存取唯讀的 Google 雲端硬碟活動和日曆活動：

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

呼叫 Google API

應用程式取得存取權權杖後，如果已授予 API 所需的存取範圍，您就可以使用權杖代表特定使用者帳戶呼叫 Google API。如要這樣做，請在 API 要求中加入存取權杖，方法是加入 access_token 查詢參數或 Authorization HTTP 標頭 Bearer 值。盡可能使用 HTTP 標頭，因為查詢字串通常會顯示在伺服器記錄中。在大多數情況下，您可以使用用戶端程式庫設定 Google API 呼叫 (例如呼叫 YouTube Live Streaming API)。

請注意，YouTube Live Streaming API 不支援服務帳戶流程。由於無法將服務帳戶連結至 YouTube 帳戶，因此嘗試透過這個流程授權要求時，系統會產生 NoLinkedYouTubeAccount 錯誤。

您可以在 OAuth 2.0 Playground 中試用所有 Google API，並查看其範圍。

HTTP GET 範例

使用 Authorization: Bearer HTTP 標頭呼叫 liveBroadcasts.list 端點 (YouTube Live Streaming API) 的呼叫可能如下所示。請注意，您需要指定自己的存取權杖：

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

以下是針對已驗證使用者，使用 access_token 查詢字串參數呼叫相同 API 的範例：

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

`curl` 範例

您可以使用 curl 指令列應用程式測試這些指令。以下是使用 HTTP 標頭選項的範例 (建議做法)：

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

或者，您也可以使用查詢字串參數選項：

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

重新整理存取權杖

存取權杖會定期到期，並成為相關 API 要求的無效憑證。如果您要求與權杖相關聯的範圍的離線存取權，則可以重新整理存取權杖，而無須提示使用者授予權限 (包括使用者不在場時)。

如要重新整理存取權杖，應用程式會向 Google 的授權伺服器 (https://oauth2.googleapis.com/token) 傳送 HTTPS POST 要求，其中包含下列參數：

欄位
`client_id`	從取得的用戶端 ID。
`client_secret`	從取得的用戶端密鑰。 (`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 https://www.googleapis.com/auth/calendar.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 和錯誤代碼。

應用程式重新導向方法

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

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

在 Android 上使用自訂 URI 配置的替代方案

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

如果您在 Android 上使用自訂配置，用於 OAuth 整合，則需要完成下列動作，才能全面改用建議的 Google 登入 Android SDK：

更新程式碼，改用 Google 登入 SDK。
在 Google API 控制台中停用自訂配置項支援功能。

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

更新程式碼，以便使用 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 是上述範例中的自訂配置重新導向 URI。如要進一步瞭解自訂 URI 配置值的格式，請參閱 redirect_uri 參數定義。
2. 請記下您需要用來設定 Google 登入 SDK 的 scope 和 client_id 要求參數。
  注意：如果您使用的是第三方程式庫，請查看程式庫的設定檔，找出這些資訊。
3. 請按照「開始將 Google 登入整合至 Android 應用程式」中的說明設定 SDK。您可以略過「取得後端伺服器的 OAuth 2.0 用戶端 ID」步驟，因為您可以重複使用先前步驟中擷取的 client_id。
4. 請按照「啟用伺服器端 API 存取權」中的操作說明進行。包括下列步驟：
  1. 使用 getServerAuthCode 方法，為您要求權限的範圍擷取驗證碼。
  2. 將驗證碼傳送至應用程式後端，以交換存取權和更新權杖。
  3. 使用擷取的存取權杖，代表使用者呼叫 Google API。
  注意：如果應用程式不需要離線存取權，請改為按照這些操作說明要求用戶端 API 存取權。
在 Google API 控制台中停用自訂配置的支援：
1. 前往「OAuth 2.0 憑證」清單，然後選取 Android 用戶端。
2. 前往「進階設定」部分，取消勾選「啟用自訂 URI 配置」核取方塊，然後按一下「儲存」，即可停用自訂 URI 配置支援功能。

啟用自訂 URI 配置

如果建議的替代方案無法解決問題，您可以按照下列操作說明，為 Android 用戶端啟用自訂 URI 配置：

前往「OAuth 2.0 憑證」清單，然後選取 Android 用戶端。
前往「進階設定」部分，勾選「啟用自訂 URI 配置」核取方塊，然後按一下「儲存」，啟用自訂 URI 配置支援功能。

在 Chrome 應用程式中使用自訂 URI 配置的替代方案

使用 Chrome Identity API，可直接將 OAuth 2.0 回應傳送至應用程式，因此不需要重新導向 URI。

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

如要使用這個網址接收授權碼，應用程式必須在本機網路伺服器上監聽。這項功能在許多平台上可行，但並非所有平台都支援。不過，如果您的平台支援此功能，這是取得授權碼的建議機制。

應用程式收到授權回應時，為了提供最佳可用性，應回應顯示 HTML 網頁，指示使用者關閉瀏覽器並返回應用程式。

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

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

手動複製/貼上 (已淘汰)

保護應用程式

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

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

Android

如要完成驗證程序，您可以使用 Google Play 開發人員帳戶 (如果您有帳戶且應用程式已在 Google Play 管理中心註冊)。如要順利完成驗證，請務必符合下列規定：

您必須在 Google Play 管理中心註冊應用程式，其套件名稱和 SHA-1 簽署憑證指紋，必須與您要完成驗證的 Android OAuth 用戶端相同。
您必須在 Google Play 管理中心取得應用程式的「管理員」權限。進一步瞭解 Google Play 管理中心的存取權管理功能。

在 Android 用戶端的「驗證應用程式擁有權」部分，按一下「驗證擁有權」按鈕，完成驗證程序。

如果驗證成功，系統會顯示通知，確認驗證程序已順利完成。否則系統會顯示錯誤提示。

如要修正驗證失敗的問題，請嘗試下列方法：

請確認您要驗證的應用程式已在 Google Play 管理中心註冊。
請確認您在 Google Play 管理中心具備該應用程式的管理員權限。

Chrome

您必須使用 Chrome 線上應用程式商店開發人員帳戶完成驗證程序。如要順利通過驗證，請務必符合下列規定：

您必須在 Chrome 線上應用程式商店開發人員資訊主頁中註冊項目，且該項目 ID 與您要完成驗證的 Chrome 擴充功能 OAuth 用戶端相同。
您必須是 Chrome 線上應用程式商店商品的發布者。進一步瞭解 Chrome 線上應用程式商店開發人員資訊主頁中的存取權管理功能。

在 Chrome 擴充功能用戶端的「Verify App Ownership」部分，按一下「Verify Ownership」按鈕，完成驗證程序。

注意：授予帳戶存取權後，請稍候幾分鐘再完成驗證程序。

如果驗證成功，系統會顯示通知，確認驗證程序已順利完成。否則系統會顯示錯誤提示。

如要修正驗證失敗的問題，請嘗試下列方法：

請確認 Chrome 線上應用程式商店開發人員資訊主頁中，有一個註冊項目，且該項目 ID 與您要完成驗證的 Chrome 擴充功能 OAuth 用戶端相同。
請確認您是應用程式的發布者，也就是應用程式的個人發布者，或是應用程式群組發布者的成員。進一步瞭解 Chrome 線上應用程式商店開發人員資訊主頁中的存取權管理功能。
如果您剛更新群組發布者清單，請確認群組發布者會員清單是否已在 Chrome 線上應用程式商店開發人員資訊主頁中同步。進一步瞭解如何同步發布商會員名單。

App Check (僅限 iOS)

App Check 功能會使用 Apple 的 App Attest 服務，驗證傳送至 Google OAuth 2.0 端點的要求是否來自您的正版應用程式，藉此保護 iOS 應用程式免於遭到未經授權的使用。這有助於降低應用程式冒用風險。

為 iOS 用戶端啟用 App Check

如要為 iOS 用戶端成功啟用 App Check，必須符合下列規定：

您必須為 iOS 用戶端指定團隊 ID。
軟體包 ID 中不得使用萬用字元，因為萬用字元可能會解析為多個應用程式。這表示軟體包 ID 不得包含星號 (*) 符號。

如要啟用 App Check，請在 iOS 用戶端的編輯檢視畫面中開啟「透過 Firebase App Check 防止 OAuth 用戶端遭到濫用」切換按鈕。

啟用 App Check 後，您會在 OAuth 用戶端的編輯檢視畫面中，看到與用戶端 OAuth 要求相關的指標。您必須強制執行 App Check，系統才會封鎖來自未經驗證來源的要求。指標監控頁面中的資訊有助於判斷何時開始執行。

為 iOS 應用程式啟用 App Check 時，您可能會看到與 App Check 功能相關的錯誤。如要修正這些錯誤，請嘗試下列操作：

確認您指定的軟體包 ID 和團隊 ID 是否有效。
確認您沒有在軟體包 ID 中使用萬用字元。

為 iOS 用戶端強制執行 App Check

為應用程式啟用 App Check 不會自動封鎖未知的要求。如要強制執行這項保護措施，請前往 iOS 用戶端的編輯檢視畫面。您會在頁面右側的「Google Identity for iOS」部分，看到 App Check 指標。這些指標包括下列資訊：

已驗證的要求次數：具有有效 App Check 權杖的要求。啟用 App Check 強制執行功能後，只有這類要求才能成功。
未經驗證的要求數量：可能過時的用戶端要求 - 要求缺少 App Check 權杖。這些要求可能來自舊版應用程式，該版本未納入 App Check 實作。
未經驗證的要求數量：來源不明的要求 - 不具備 App Check 權杖且看起來不像是來自您應用程式的要求。
未經驗證的要求數量：無效的要求 - 具備無效 App Check 權杖的要求，可能來自模擬環境，或是試圖冒用您應用程式的偽造用戶端。

查看這些指標，瞭解強制執行 App Check 對使用者有何影響。

如要強制執行應用程式檢查，請按一下「強制執行」ENFORCE按鈕，然後確認您的選擇。強制執行功能啟用後，系統會拒絕來自用戶端的所有未經驗證要求。

注意：啟用強制執行後，變更最多可能需要 15 分鐘才會生效。

取消強制執行 iOS 用戶端的 App Check

取消強制執行應用程式 App Check 後，系統就會停止強制執行，並允許從用戶端傳送至 Google OAuth 2.0 端點的所有要求，包括未經驗證的要求。

如要為 iOS 用戶端停用 App Check，請前往 iOS 用戶端的編輯檢視畫面，然後按一下「UNENFORCE」按鈕並確認您的選擇。

注意：停用 App Check 後，變更最多可能需要 15 分鐘才會生效。

為 iOS 用戶端停用 App Check

為應用程式停用 App Check 後，系統就會停止所有 App Check 監控和強制執行作業。建議您改為停用 App Check，以便繼續監控用戶端的指標。

如要為 iOS 用戶端停用 App Check，請前往 iOS 用戶端的編輯檢視畫面，然後關閉「Protect your OAuth client from abuse with Firebase App Check」切換按鈕。

注意：停用 App Check 後，變更內容最多可能需要 15 分鐘才會生效。

延伸閱讀

IETF 目前最佳做法「原生應用程式的 OAuth 2.0」中，已建立許多這裡所述的最佳做法。

導入跨帳戶防護

您還可以透過 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

如要進一步瞭解如何實作跨帳戶保護功能，以及查看可用的完整事件清單，請參閱「透過跨帳戶保護功能保護使用者帳戶」一文。

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

程式庫與範例

必要條件

為專案啟用 API

建立授權憑證

Android

iOS

UWP

找出存取權範圍

取得 OAuth 2.0 存取權杖

步驟 1：產生驗證碼和驗證碼挑戰

建立程式碼驗證器

建立驗證碼問題

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

授權網址範例

自訂 URI 配置

回送 IP 位址

步驟 3：Google 提示使用者同意

錯誤

admin_policy_enforced

disallowed_useragent

Android

iOS

org_internal

invalid_grant

redirect_uri_mismatch

invalid_request

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

步驟 5：交換授權碼，取得更新和存取權杖

步驟 6：檢查使用者授予的範圍

呼叫 Google API

HTTP GET 範例

curl 範例

重新整理存取權杖

撤銷權杖

應用程式重新導向方法

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

在 Android 上使用自訂 URI 配置的替代方案

如何遷移至 Google 帳戶登入 Android SDK

啟用自訂 URI 配置

在 Chrome 應用程式中使用自訂 URI 配置的替代方案

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

手動複製/貼上 (已淘汰)

保護應用程式

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

Android

Chrome

App Check (僅限 iOS)

為 iOS 用戶端啟用 App Check

為 iOS 用戶端強制執行 App Check

取消強制執行 iOS 用戶端的 App Check

為 iOS 用戶端停用 App Check

延伸閱讀

導入跨帳戶防護

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

`curl` 範例