行動與電腦版應用程式的 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。

資料庫與示例

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

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

先備知識

為專案啟用 API

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

如何在專案中啟用 API：

1. Google API Console中的Open the API Library 。
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 授權之前，建議您找出應用程式需要權限存取的範圍。

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

OAuth 2.0 API 範圍文件完整列出了可用於存取 Google API 的範圍。

取得 OAuth 2.0 存取權杖

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

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

Google 支援 Code Exchange 金鑰證明 (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 伺服器

如要取得使用者授權，請透過 https://accounts.google.com/o/oauth2/v2/auth 將要求傳送至 Google 的授權伺服器。這個端點會處理執行中的工作階段查詢、驗證使用者身分，並取得使用者同意。端點只能透過 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.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

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 伺服器的回應，並指出是否已獲得任何存取權，因此在這個階段無須採取任何行動。該回應會在下列步驟中說明。

步驟 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

應用程式取得存取權杖後，在獲得 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)，其中包含下列參數：

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

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 和錯誤代碼。

延伸閱讀

「適用於原生應用程式的 OAuth 2.0 最佳做法」「IETF 現行最佳做法」提供本文所述的許多最佳做法。