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

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

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

已安裝的應用程式會發布至個別裝置，假設這些應用程式已不適用 不能保存秘密即便使用者正在使用應用程式，應用程式也能存取 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. 在「資料庫」頁面中，找出並啟用 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 用戶端命名，然後將其他欄位設為 或適當。

識別存取權範圍

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

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

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

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 個半形字元

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

建立代碼挑戰

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

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) 連線。

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

授權網址範例

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

這些網址都相同，但 redirect_uri 參數的值除外。網址 也包含必要的 response_type 和 client_id 參數 做為選用的 state 參數每個網址都含有換行符號和 且可讀性高

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

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 伺服器會指出是否已獲得任何存取權。詳細說明請參閱 請按照下列步驟進行。

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

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

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

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

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

下列程式碼片段為要求範例：

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": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

呼叫 Google API

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

請注意，YouTube Live Streaming API 不支援服務帳戶流程。因為 沒有將服務帳戶連結至 YouTube 帳戶的方法，會嘗試用這個 流程會產生 NoLinkedYouTubeAccount 錯誤。

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

HTTP GET 範例

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

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 要求的無效憑證。個人中心 可以更新存取權杖，而不必提示使用者授予權限 (包括 不存在的屬性值)。

為了重新整理存取權杖，應用程式會傳送 HTTPS POST 向 Google 的授權伺服器 (https://oauth2.googleapis.com/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 原生應用程式建立了許多本文所述的最佳做法。