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

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

OAuth 2.0 可讓使用者與應用程式共用特定資料,同時保有使用者名稱、密碼和其他資訊的私密性。 舉例來說,應用程式可透過 OAuth 2.0 取得權限,以便將影片上傳至使用者的 YouTube 頻道。

已安裝的應用程式是發布至個別裝置,系統會假設這些應用程式無法保存密鑰。當使用者位於應用程式期間,或在背景執行時,這些 API 可以存取 Google API。

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

替代方案

如果是行動應用程式,建議您在 AndroidiOS 裝置上使用 Google 登入。Google 登入用戶端程式庫會處理驗證和使用者授權,而且實作方式可能比本文所述的較低層級通訊協定簡單。

如果應用程式是在不支援系統瀏覽器的裝置上運作,或提供有限輸入功能 (例如電視、遊戲主機、攝影機或印表機),請參閱電視和裝置適用的 OAuth 2.0在電視和有限輸入裝置中登入的說明。

資料庫與示例

建議您使用下列程式庫和範例,協助您實作本文所述的 OAuth 2.0 流程:

必要條件

為專案啟用 API

呼叫 Google API 的所有應用程式都必須在 API Console中啟用這些 API。

如要在專案中啟用 API,請按照下列步驟操作:

  1. Open the API Library (位於 Google API Console中)。
  2. If prompted, select a project, or create a new one.
  3. 在「媒體庫」頁面中,尋找並啟用 YouTube Data API。找出應用程式要使用的任何其他 API,並啟用這些 API。

建立授權憑證

凡是使用 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」應用程式類型。
  2. 輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的 Credentials page 中,以便識別用戶端。
  3. 輸入 Android 應用程式的套件名稱。您可以在應用程式資訊清單檔案中,透過 <manifest> 元素的 package 屬性定義這個值。
  4. 請輸入應用程式發布的 SHA-1 簽署憑證指紋。
    • 如果您的應用程式使用 Google Play 應用程式簽署功能,請從 Play 管理中心的應用程式簽署頁面複製 SHA-1 指紋。
    • 如果您自行管理 KeyStore 和簽署金鑰,請使用 Java 隨附的 keytool 公用程式以使用者可理解的格式列印憑證資訊。複製 keytool 輸出內容 Certificate fingerprints 區段中的 SHA1 值。詳情請參閱 Google API Android 說明文件中的「驗證用戶端」一節。
  5. (選用) 驗證 Android 應用程式的擁有權
  6. 點選「建立」
iOS
  1. 選取「iOS」iOS應用程式類型。
  2. 輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的 Credentials page 中,以便識別用戶端。
  3. 輸入應用程式的軟體包 ID。軟體包 ID 是應用程式資訊屬性清單資源檔案中 CFBundleIdentifier 金鑰的值,info.plist。這個值最常顯示在 Xcode 專案編輯器的「一般」窗格或「簽署與功能」窗格中。此外,在 Apple App Store Connect 網站上,應用程式「應用程式資訊」頁面的「一般資訊」部分也會顯示軟體包 ID。
  4. (選填)

    如果應用程式已在 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

  5. (選填)

    輸入團隊 ID。詳情請參閱 Apple 開發人員帳戶說明文件中的「找出團隊 ID」一節。

  6. 點選「建立」
UWP
  1. 選取「通用 Windows Platform」應用程式類型。
  2. 輸入 OAuth 用戶端的名稱。這個名稱會顯示在專案的 Credentials page 中,以便識別用戶端。
  3. 輸入應用程式的 Microsoft Store ID (最多 12 個字元)。您可以在 Microsoft 合作夥伴中心的「應用程式管理」部分的「應用程式身分」頁面中找到這個值。
  4. 點選「建立」

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

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

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

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

使用 Android SDK 適用的 Google 登入,將 OAuth 2.0 回應直接傳送至應用程式,不需要重新導向 URI。

如何改用適用於 Android SDK 的 Google 登入功能

如果您目前使用自訂配置來整合 Android 裝置上的 OAuth,則必須完成下列操作,才能完全改用建議的 Android SDK 專用 Google 登入機制:

  1. 更新程式碼即可使用 Google 登入 SDK。
  2. 停用 Google API 控制台中自訂配置的支援。

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

使用 Chrome Identity API,將 OAuth 2.0 回應直接提供給應用程式,不必再使用重新導向 URI。

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

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

Android

如要完成驗證程序,您可以使用 Google Play 開發人員帳戶 (如果您有 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 擴充功能用戶端的「驗證應用程式擁有權」部分中,按一下「驗證擁有權」按鈕,完成驗證程序。

注意:授予帳戶存取權後,請稍待幾分鐘,然後完成驗證程序。

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

如要解決驗證失敗的問題,請嘗試以下方法:

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

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

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

為了讓應用程式更方便使用,應用程式收到授權回應時,應顯示 HTML 網頁,指示使用者關閉瀏覽器並返回應用程式。

建議用法 macOS、Linux 和 Windows 桌面 (而非通用 Windows 平台) 應用程式
表單值 將應用程式類型設為「Desktop app」。

手動複製/貼上

識別存取權範圍

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

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

YouTube Data API 第 3 版使用下列範圍:

狙擊鏡
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 支援程式碼交換金鑰證明 (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 伺服器傳送要求

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

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

參數
client_id 必填

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

redirect_uri 必填

決定 Google 授權伺服器如何傳送回應給您的應用程式。已安裝的應用程式有幾種重新導向選項,您必須依據特定的重新導向方式來設定授權憑證

這個值必須與您在用戶端的 API Console Credentials page中設定的 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:porthttp://[::1]:port

向平台查詢相關的回送 IP 位址,並在隨機的可用通訊埠啟動 HTTP 事件監聽器。請將 port 替換成應用程式監聽的實際通訊埠編號。

請注意,行動應用程式支援回送 IP 位址重新導向選項,已 淘汰

response_type 必填

決定 Google OAuth 2.0 端點是否傳回授權碼。

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

scope 必填

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

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

YouTube Data API 第 3 版使用下列範圍:

狙擊鏡
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 的要求中不存在,code_challenge_method 的值會預設為 plain。這個參數唯一支援的值是 S256plain

state 建議

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

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

login_hint 選用

如果應用程式知道要驗證的使用者,就能使用這項參數向 Google 驗證伺服器提供提示。伺服器會使用提示來簡化登入流程,方法是在登入表單中預先填入電子郵件欄位,或是選取適當的多帳戶登入工作階段。

將參數值設為電子郵件地址或 sub ID,這相當於使用者的 Google ID。

授權網址範例

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

每個網址都會要求存取權,允許存取使用者的 YouTube 帳戶。

兩者的網址相同,除了 redirect_uri 參數的值以外。網址也包含必要的 response_typeclient_id 參數,以及選用的 state 參數。每個網址都包含換行符號和空格,以便判讀。

自訂 URI 配置

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 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.readonly&
 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

如果 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 Credentials page API Console取得的用戶端 ID。
client_secret Credentials page API Console取得的用戶端密鑰。
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 注意:只有在要求包含身分範圍 (例如 openidprofileemail) 時,才會傳回這個屬性。這個值是 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",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

呼叫 Google API

應用程式取得存取權杖後,如果 API 所需的存取權範圍已獲準,您可以使用權杖,代表指定使用者帳戶呼叫 Google API。方法是在傳送至 API 的要求中加入存取權杖,方法是加入 access_token 查詢參數或 Authorization HTTP 標頭 Bearer 值。建議您盡可能使用 HTTP 標頭,因為查詢字串通常會顯示在伺服器記錄檔中。在多數情況下,您可以使用用戶端程式庫來設定對 Google API 的呼叫 (例如呼叫 YouTube Data API 時)。

請注意,YouTube Data API 僅支援擁有及管理多個 YouTube 頻道的 YouTube 內容擁有者 (例如唱片標籤和電影公司) 的服務帳戶。

您可以試用所有 Google API,並前往 OAuth 2.0 Playground 查看其範圍。

HTTP GET 範例

使用 Authorization: Bearer HTTP 標頭呼叫 youtube.channels 端點 (YouTube Data API) 可能如下所示。請注意,您必須指定自己的存取權杖:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

以下是使用 access_token 查詢字串參數對已驗證使用者的呼叫相同 API:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl 範例

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

重新整理存取權杖

存取權杖會定期過期,並從相關 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」說明瞭本文所述的許多最佳做法。