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

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

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

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

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

程式庫與範例

如果是行動應用程式，建議使用最新版的 Google Identity Services 原生程式庫 (適用於 Android) 和 Google 登入原生程式庫 (適用於 iOS)。這些程式庫會處理使用者授權，且相較於本文所述的低階通訊協定，實作起來更簡單。

如果應用程式是在不支援系統瀏覽器或輸入功能受限的裝置上執行 (例如電視、遊戲主機、相機或印表機)，請參閱「電視和裝置適用的 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，並一併啟用。

建立授權憑證

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

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

找出存取權範圍

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

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

YouTube Data API v3 使用下列範圍：

「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 伺服器傳送要求

如要取得使用者授權，請在 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"
}

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

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

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

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

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

舉例來說，下列存取權杖回應範例指出，使用者已授予應用程式權限，可查看、編輯及永久刪除使用者的 YouTube 影片、評分、留言和字幕：

  {
    "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 內容擁有者，例如唱片公司和電影製片廠。

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

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

應用程式重新導向方法

保護應用程式

以時間為依據的存取權

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

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

延伸閱讀

IETF 目前的最佳做法「OAuth 2.0 for Native Apps」確立了許多本文記錄的最佳做法。