在行動版和電腦版應用程式中使用 OAuth 2.0

本文檔解釋了安裝在手機、平板電腦和電腦等裝置上的應用程式如何使用 Google 的 OAuth 2.0 端點來授權存取 YouTube Analytics API 或 YouTube Reporting API。

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

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

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

程式庫與範例

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

如果應用程式是在不支援系統瀏覽器或輸入功能有限的裝置上執行，例如電視、遊戲主機、相機或印表機，請參閱「電視和裝置適用的 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 Analytics API 和 YouTube Reporting API。許多擷取 YouTube 數據分析資料的應用程式，也會與 YouTube Data API 介接。找出應用程式會使用的其他 API，並一併啟用。

建立授權憑證

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

1. Go to the Clients page.
2. 按一下「建立用戶端」。
3. 以下各節說明 Google 授權伺服器支援的用戶端類型。選擇適合應用程式的用戶端類型、為 OAuth 用戶端命名，並視需要設定表單中的其他欄位。

ms-app://YOUR_APP_PACKAGE_SID

找出存取權範圍

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

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

YouTube 數據分析 API 使用下列範圍：

YouTube Reporting API 使用下列範圍：

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 個字元。

驗證碼應有足夠的熵，讓他人無法猜出值。

建立驗證碼問題

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

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

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

授權 URL 範例

下面的標籤頁顯示了不同重定向 URI 選項的範例授權 URL。

除了 redirect_uri 參數的值之外，這些 URL 完全相同。網址也包含必要參數 response_type 和 client_id，以及選用參數 state。每個網址都包含換行符號和空格，方便閱讀。

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.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%2Fyt-analytics.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&
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/yt-analytics.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/yt-analytics.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 的呼叫（例如，當 呼叫 YouTube Analytics API 時）。

請注意，YouTube Analytics API 不支援服務帳戶流程。YouTube 報告 API 僅支援擁有和管理多個 YouTube 頻道的 YouTube 內容擁有者的服務帳戶，例如唱片公司和電影製片廠。

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

HTTP GET 範例

使用 Authorization: Bearer HTTP 標頭呼叫 reports.query 端點（YouTube Analytics API）可能如下所示。請注意，您必須指定自己的存取權杖：

GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

curl 範例

您可以使用 curl 命令列應用程式測試這些命令。以下是一個使用 HTTP 標頭選項（建議）的範例：

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

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

curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

刷新訪問令牌

存取令牌會定期過期，過期後將無法用於相關的 API 請求。如果您要求離線存取與令牌關聯的範圍，則可以在不提示使用者許可的情況下重新整理存取權杖（包括使用者不在場時）。

若要刷新存取權杖，您的應用程式會向 Google 的授權伺服器 (https://oauth2.googleapis.com/token) 發送 HTTPS POST 請求，其中包含以下參數：

以下程式碼片段展示了一個範例請求：

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

應用程式重定向方法

保護您的應用

以時間為依據的存取權

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

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

延伸閱讀

IETF 最佳實踐 OAuth 2.0 for Native Apps 確立了許多此處記錄的最佳實踐。