適用於 iOS 和電腦版應用程式的 OAuth 2.0

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

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

已安裝的應用程式會發布到個別裝置，且假設這些應用程式無法保留密碼。應用程式在使用者面前或在背景執行時，都可以存取 Google API。

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

程式庫與範例

如果是 iOS 應用程式，建議使用最新版的「使用 Google 帳戶登入」 iOS SDK。這個 SDK 會處理使用者授權，而且相較於本指南所述的低階通訊協定，實作起來更簡單。

如果應用程式是在不支援系統瀏覽器或輸入功能有限的裝置上執行 (例如電視、遊戲主機、相機或印表機)，請參閱「OAuth 2.0 for TVs & Devices」或「Sign-In on TVs and Limited Input Devices」。

必要條件

為專案啟用 API

凡是呼叫 Google API 的應用程式，都必須在 API 控制台中啟用這些 API。

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

在 Google API 控制台中開啟 API 程式庫。
按照系統說明選取專案，或建立新專案。
API 程式庫會列出所有可用的 API，並按照產品系列及熱門程度分組。如果清單裡找不到您想啟用的 API，請使用搜尋功能，或點選所屬產品系列的「查看全部」。
選取要啟用的 API，然後按一下「啟用」按鈕。
如果系統顯示提示，請啟用帳單功能。
如果系統顯示提示，請詳閱並接受 API 的《服務條款》。

建立授權憑證

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

前往「用戶端」頁面。
按一下「建立用戶端」。
以下各節說明 Google 授權伺服器支援的用戶端類型。選擇適合應用程式的用戶端類型，為 OAuth 用戶端命名，並視需要設定表單中的其他欄位。

iOS

選取「iOS」iOS應用程式類型。
輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的「客戶」頁面，用於識別客戶。
輸入應用程式的軟體包 ID。軟體包 ID 是應用程式資訊屬性清單資源檔案 (info.plist) 中 CFBundleIdentifier 鍵的值。這個值最常顯示在 Xcode 專案編輯器的「General」窗格或「Signing & Capabilities」窗格中。您也可以在 Apple App Store Connect 網站上，應用程式「App 詳細資料」頁面的「一般資訊」部分中，找到軟體包 ID。
確認您使用的是正確的應用程式軟體包 ID，因為如果您使用 App Check 功能，就無法變更軟體包 ID。
(選用)
如果應用程式已發布至 Apple App Store，請輸入應用程式的 App Store ID。Store 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 開發人員帳戶說明文件中的「找出團隊 ID」。
注意：如果您要為用戶端啟用 App Check，則必須填寫「團隊 ID」欄位。
(選用)
為 iOS 應用程式啟用 App Check。啟用 App Check 後，系統會使用 Apple 的 App Attest 服務，驗證 OAuth 用戶端發出的 OAuth 2.0 要求是否來自您的應用程式，藉此降低應用程式遭冒用的風險。進一步瞭解如何為 iOS 應用程式啟用 App Check。
點選「建立」。

UWP

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

如果是 UWP 應用程式，重新導向 URI 會使用應用程式專屬的套件安全 ID (SID) 形成。您可以在 Visual Studio 專案的 Package.appxmanifest 檔案中找到應用程式的 Package SID。

在 Google Cloud 控制台中建立用戶端 ID 時，您必須使用下列格式指定重新導向 URI，並使用套件 SID 的小寫值：

ms-app://YOUR_APP_PACKAGE_SID

注意：OAuth 2.0 重新導向必須使用 ms-app:// 結構定義，才能正常運作。這個配置用於啟動通訊協定，讓作業系統在使用者於瀏覽器中完成驗證後，啟動應用程式並傳送 Google 的授權回應。

如為 UWP 應用程式，自訂 URI 配置不得超過 39 個字元，詳情請參閱 Microsoft 說明文件。

找出存取權範圍

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

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

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。您可以在 Cloud Console 的「用戶端」頁面找到這個值。

redirect_uri

必要

決定 Google 授權伺服器如何將回應傳送至應用程式。已安裝的應用程式有多種重新導向選項，您在設定授權憑證時，會考量到特定的重新導向方法。

這個值必須與用戶端 Cloud 控制台「用戶端」頁面中設定的 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 向使用者顯示的同意畫面。

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

code_challenge

建議

指定編碼的 code_verifier，在授權碼交換期間會做為伺服器端驗證。詳情請參閱建立程式碼挑戰。

code_challenge_method

建議

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

state

建議

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

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

重要事項：OAuth 用戶端必須按照 OAuth2 規格中的說明，防止發生 CSRF。其中一種做法是使用 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 Workspace 管理員的政策，Google 帳戶無法授權一或多個要求範圍。如要進一步瞭解管理員如何限制存取所有範圍，或限制存取機密和受限範圍，直到明確授予 OAuth 用戶端 ID 存取權為止，請參閱 Google Workspace 管理員說明文章「控管哪些第三方應用程式和內部應用程式可存取 Google Workspace 資料」。

`disallowed_useragent`

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

iOS 和 macOS 開發人員在 WKWebView 中開啟授權要求時，可能會遇到這項錯誤。開發人員應改用 iOS 程式庫，例如 Google 登入 for iOS 或 OpenID Foundation 的 AppAuth for iOS。

如果 iOS 或 macOS 應用程式在內嵌的使用者代理程式中開啟一般網頁連結，且使用者從您的網站前往 Google 的 OAuth 2.0 授權端點，網頁程式開發人員可能會遇到這個錯誤。開發人員應允許一般連結在作業系統的預設連結處理常式中開啟，包括通用連結處理常式或預設瀏覽器應用程式。SFSafariViewController 程式庫也是支援的選項。

`org_internal`

要求中的 OAuth 用戶端 ID 屬於專案，該專案限制只能存取特定 Google Cloud 機構中的 Google 帳戶。如要進一步瞭解這個設定選項，請參閱「設定 OAuth 同意畫面」說明文章中的「使用者類型」一節。

`deleted_client`

用來提出要求的 OAuth 用戶端已遭刪除。您可以手動刪除，也可以讓系統在未使用的用戶端中自動刪除。刪除後的 30 天內均可還原用戶端。瞭解詳情。

`invalid_grant`

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

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

`redirect_uri_mismatch`

授權要求中傳遞的 redirect_uri 與 OAuth 用戶端 ID 的授權重新導向 URI 不符。在 Google Cloud 控制台的「用戶端」頁面中，查看已授權的重新導向 URI。

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

redirect_uri 參數可能參照已淘汰且不再支援的 OAuth 頻外 (OOB) 流程。請參閱遷移指南，更新整合項目。

`invalid_request`

您提出的要求有誤。可能原因如下：

要求格式有誤
要求缺少必要參數
要求使用的授權方法不受 Google 支援。確認 OAuth 整合項目使用建議的整合方法
重新導向 URI 使用了不支援的自訂配置。如果看到「Android 或 Chrome 應用程式不支援自訂 URI 配置」錯誤訊息，請參閱這篇文章，進一步瞭解自訂 URI 配置的替代方案。

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

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

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

步驟 5：將授權碼換成更新和存取權杖

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

欄位
`client_id`	從 Cloud 控制台的「用戶端」頁面取得的用戶端 ID。
`client_secret`	選填從 Cloud Console 的「用戶端」頁面取得的用戶端密鑰。
`code`	初始要求傳回的授權碼。
`code_verifier`	您在步驟 1 中建立的驗證碼。
`grant_type`	如 OAuth 2.0 規格所述，這個欄位的值必須設為 `authorization_code`。
`redirect_uri`	Cloud Console 中專案的「用戶端」頁面 () 列出的其中一個重新導向 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&
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`	可用於取得新存取權杖的權杖。更新權杖在使用者撤銷存取權或更新權杖到期前都有效。請注意，系統一律會為已安裝的應用程式傳回重新整理權杖。
`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"
}

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

要求多項權限 (範圍) 時，使用者可能不會授予應用程式所有權限。應用程式必須驗證實際授予的範圍，並妥善處理部分權限遭拒的情況，通常是停用依賴這些遭拒範圍的功能。

不過也有例外狀況。如果 Google Workspace Enterprise 應用程式具有網域範圍的授權委派，或是標示為可信任，就會略過詳細權限同意畫面。這類應用程式不會顯示精細權限同意畫面。應用程式會收到所有要求的範圍，或完全沒有。

詳情請參閱「如何處理精細權限」。

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

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

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

呼叫 Google API

應用程式取得存取權杖後，如果已授予 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

重新整理存取權杖

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

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

欄位
`client_id`	從 API 控制台取得的用戶端 ID。
`client_secret`	選填從 API 控制台取得的用戶端密鑰。 (如果用戶端註冊為 Android、iOS 或 Chrome 應用程式，則不適用 `client_secret`)。
`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&
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 配置

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

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

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

迴路 IP 位址 (macOS、Linux、Windows 電腦)

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

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

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

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

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

保護應用程式

驗證 Chrome 應用程式擁有權

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

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

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

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

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

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

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

請確認 Chrome 線上應用程式商店開發人員資訊主頁中，已註冊與您要驗證的 Chrome 擴充功能 OAuth 用戶端具有相同項目 ID 的項目。
請確認您是應用程式的發布者，也就是應用程式的個人發布者，或是應用程式的群組發布者成員。進一步瞭解 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 會對使用者造成哪些影響。

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

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

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

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

如要對 iOS 用戶端取消強制執行 App Check，請前往 iOS 用戶端的編輯畫面，然後按一下「取消強制執行」按鈕並確認選擇。

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

為 iOS 用戶端停用 App Check

為應用程式停用 App Check 後，系統會停止所有 App Check 監控和強制執行。請考慮取消強制執行 App Check，以便繼續監控用戶端的指標。

如要為 iOS 用戶端停用 App Check，請前往 iOS 用戶端的編輯畫面，然後關閉「透過 Firebase App Check 防止 OAuth 用戶端遭到濫用」切換按鈕。

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

以時間為依據的存取權

使用者可授予應用程式限時存取權，讓應用程式在一段時間內存取資料，以完成特定操作。在同意聲明流程中，使用者可選擇授予限時存取權，這項功能適用於特定 Google 產品。例如 Data Portability API 可讓您一次性轉移資料。

使用者授予應用程式限時存取權時，更新權杖會在指定時間後失效。請注意，在特定情況下，重新整理權杖可能會提早失效；詳情請參閱這些案例。在這種情況下，授權碼交換回應中傳回的 refresh_token_expires_in 欄位，代表更新權杖到期前的剩餘時間。

延伸閱讀

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

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

適用於 iOS 和電腦版應用程式的 OAuth 2.0 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

程式庫與範例

必要條件

為專案啟用 API

建立授權憑證

iOS

UWP

找出存取權範圍

取得 OAuth 2.0 存取權杖

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

建立程式碼驗證碼

建立驗證碼問題

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

授權網址範例

自訂 URI 配置

迴路 IP 位址

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

錯誤

admin_policy_enforced

disallowed_useragent

org_internal

deleted_client

invalid_grant

redirect_uri_mismatch

invalid_request

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

步驟 5：將授權碼換成更新和存取權杖

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

呼叫 Google API

HTTP GET 範例

curl 範例

重新整理存取權杖

權杖撤銷

應用程式重新導向方法

自訂 URI 配置

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

迴路 IP 位址 (macOS、Linux、Windows 電腦)

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

保護應用程式

驗證 Chrome 應用程式擁有權

App Check (僅限 iOS)

為 iOS 用戶端啟用 App Check

對 iOS 用戶端強制執行 App Check

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

為 iOS 用戶端停用 App Check

以時間為依據的存取權

延伸閱讀

導入跨帳戶防護功能

適用於 iOS 和電腦版應用程式的 OAuth 2.0

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`deleted_client`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

`curl` 範例