使用 OAuth 2.0 存取 Google API

Google API 使用 OAuth 2.0 通訊協定進行驗證和授權。Google 支援常見的 OAuth 2.0 情境,例如網路伺服器、用戶端、已安裝和受限制的輸入應用程式應用程式。

首先,請從 Google API Console 取得 OAuth 2.0 用戶端憑證。接著,用戶端應用程式會從 Google 授權伺服器要求存取存取憑證、從回應中擷取憑證,並將憑證傳送至您要存取的 Google API。如想瞭解 Google 如何使用互動式 OAuth 2.0 (包括使用自己的用戶端憑證),請進行 OAuth 2.0 Playground 的互動式示範。

本頁概述 Google 支援的 OAuth 2.0 授權情境,並提供詳細內容的連結。如要進一步瞭解如何使用 OAuth 2.0 進行驗證,請參閱 OpenID Connect 一文。

基本步驟

所有應用程式皆採用基本模式,以使用 OAuth 2.0 存取 Google API。大致上,您按照下列五個步驟操作:

1. 從 Google API Console取得 OAuth 2.0 憑證。

造訪 Google API Console 以取得 OAuth 2.0 憑證,例如 Google 和您的應用程式均知道的用戶端 ID 和用戶端密鑰。這組值會因建構的應用程式類型而異。舉例來說,JavaScript 應用程式並不需要密鑰,但網路伺服器應用程式卻需要。

2. 從 Google 授權伺服器取得存取憑證。

您的應用程式必須先取得存取憑證才能存取這個 API,才能存取 Google API。一組存取憑證可授予不同程度的多個 API 存取權限。名為 scope 的變數參數會控制存取憑證允許的資源和運算。在存取憑證要求期間,您的應用程式會在 scope 參數中傳送一或多個值。

建立此要求的方法有很多種,視建立的應用程式類型而定。例如,JavaScript 應用程式可能會使用瀏覽器重新導向 Google 來要求存取憑證,而在沒有瀏覽器的裝置上安裝應用程式則會使用網路服務要求。

某些要求會要求使用者進行驗證,使用者可以透過自己的 Google 帳戶登入。登入後,系統會詢問使用者是否願意授予應用程式所需的一或多項權限。這個過程稱為使用者同意聲明

如果使用者將權限授予至少一項權限,Google 授權伺服器就會將您的應用程式存取憑證 (或應用程式用來取得存取憑證的授權碼) 傳送給您的應用程式,並附上該權杖授予的存取權範圍清單。如果使用者未授予權限,伺服器會傳回錯誤。

一般而言,最佳做法是以漸進的方式要求範圍,因為需要存取時,而非一開始。舉例來說,如果應用程式要支援將活動儲存至日曆,除非使用者按下 [新增至日曆] 按鈕,否則應用程式不得要求 Google 日曆存取權;請參閱逐步授權

3. 檢查使用者授予的存取權範圍。

請根據存取 Google API 的存取權,比較存取憑證回應中涵蓋的範圍,以存取應用程式功能所需的功能。如果應用程式無法存取相關的 API,就必須停用所有功能。

即使您的使用者已授予所有要求範圍,要求中的範圍可能與回應中的範圍不符。參閱每個 Google API 的說明文件,以取得存取所需的範圍。API 可將多個範圍字串值對應到單一存取權範圍,並針對要求中所有允許的值傳回相同的範圍字串。範例:當應用程式要求使用者授權 https://www.google.com/m8/feeds/ 範圍時,Google People API 可能會傳回 https://www.googleapis.com/auth/contacts 的範圍;Google People API 方法 people.updateContact 需要授予 https://www.googleapis.com/auth/contacts 的授予範圍。

4. 將存取憑證傳送至 API。

應用程式取得存取憑證後,就會透過 HTTP Authorization 要求標頭將憑證傳送至 Google API。您或許可以傳送憑證做為 URI 查詢字串參數,但我們不建議這麼做,因為 URI 參數最後可能在完全安全的安全紀錄檔中。此外,最好避免建立不必要的 URI 參數名稱。

存取憑證僅適用於憑證要求的 scope 中描述的一組操作與資源。例如,如果核發憑證給 Google Calendar API,系統就不會授予 Google Contacts API 的存取權。不過,您可以將類似的存取憑證多次傳送至 Google Calendar API,以執行類似的作業。

5. 視需要重新整理存取憑證。

存取憑證的生命週期有限。如果您的應用程式需要存取單一 API 的單次有效存取憑證,更新憑證可讓應用程式取得新的存取憑證。

應用情境

網路伺服器應用程式

Google OAuth 2.0 端點支援使用語言及架構 (如 PHP、Java、Python、Ruby 和 ASP.NET) 的網路伺服器應用程式。

當您的應用程式重新導向至瀏覽器或 Google 網址時,系統會啟動授權序列;該網址會包含查詢參數,指出要求存取權類型。 Google 會處理使用者驗證、工作階段選取和使用者同意聲明。這是一種授權碼,可供應用程式用來交換存取憑證和更新憑證。

應用程式必須儲存更新憑證以供日後使用,並使用存取憑證存取 Google API。存取權杖到期後,應用程式會使用重新整理的權杖取得新的權杖。

您的應用程式會向 Google 授權伺服器傳送憑證要求、接收授權碼、交換憑證的程式碼,以及使用憑證呼叫 Google API 端點。

詳情請參閱為網路伺服器應用程式使用 OAuth 2.0 一文。

應用程式已安裝

Google OAuth 2.0 端點支援在裝置上安裝的裝置,例如電腦、行動裝置和平板電腦。透過 Google API Console 建立用戶端 ID 時,請指定這是已安裝的應用程式,然後選取 Android、Chrome 應用程式、iOS、通用 Windows Platform (UWP) 或電腦版應用程式做為應用程式類型。

這個程序會產生用戶端 ID,在某些情況下甚至會建構用戶端密鑰,讓您嵌入應用程式的原始碼。(在這個情況下,用戶端密鑰顯然並不屬於密鑰)。

當您的應用程式重新導向至瀏覽器或 Google 網址時,系統會啟動授權序列;該網址會包含查詢參數,指出要求存取權類型。 Google 會處理使用者驗證、工作階段選取和使用者同意聲明。這是一種授權碼,可供應用程式用來交換存取憑證和更新憑證。

應用程式必須儲存更新憑證以供日後使用,並使用存取憑證存取 Google API。存取權杖到期後,應用程式會使用重新整理的權杖取得新的權杖。

您的應用程式會向 Google 授權伺服器傳送憑證要求、接收授權碼、交換憑證的程式碼,以及使用憑證呼叫 Google API 端點。

詳情請參閱針對已安裝的應用程式使用 OAuth 2.0

用戶端 (JavaScript) 應用程式

Google OAuth 2.0 端點支援在瀏覽器中執行的 JavaScript 應用程式。

當您的應用程式重新導向至瀏覽器或 Google 網址時,系統會啟動授權序列;該網址會包含查詢參數,指出要求存取權類型。 Google 會處理使用者驗證、工作階段選取和使用者同意聲明。

結果是存取憑證,用戶端必須先驗證該憑證,才能將其納入 Google API 要求中。符記到期時,應用程式會重複此程序。

您的 JS 應用程式會傳送憑證要求給 Google 授權伺服器、接收憑證、驗證憑證,並使用憑證呼叫 Google API 端點。

詳情請參閱針對用戶端應用程式使用 OAuth 2.0

輸入受限裝置的應用程式

Google OAuth 2.0 端點支援在有限輸入裝置 (例如遊戲主機、攝影機和印表機) 上執行的應用程式。

授權序列會先向向 Google 網址提出授權碼要求的應用程式進行授權碼。回應包含幾個參數,包括網址和應用程式向使用者顯示的程式碼。

使用者從裝置取得網址和程式碼,然後切換到具有更豐富輸入功能的獨立裝置或電腦。使用者啟動瀏覽器,瀏覽至指定的網址,登入並輸入代碼。

同時,應用程式會以指定的時間間隔輪詢 Google 網址。使用者核准存取權後,Google 伺服器的回應就會包含存取憑證並更新憑證。應用程式必須儲存更新憑證以供日後使用,並使用存取憑證存取 Google API。存取權杖到期之後,應用程式會使用重新整理憑證來取得新的權杖。

使用者在設有瀏覽器的另一部裝置上登入

詳情請參閱為裝置使用 OAuth 2.0 一文。

服務帳戶

Google API (例如 Prediction API 和 Google Cloud Storage) 可在不存取使用者資訊的情況下,代表您的應用程式執行動作。在這些情況下,您的應用程式必須證明自己是 API 的擁有者,但不需要取得使用者同意。同樣地,在企業環境中,應用程式也可以要求將資源存取權授予某些資源。

針對這類伺服器對伺服器的互動,您需要「服務帳戶」,這是屬於您應用程式的帳戶,並不屬於個別使用者。您的應用程式會代表服務帳戶呼叫 Google API,您無須取得使用者同意。(在非服務帳戶的情況下,您的應用程式會代表使用者呼叫 Google API,有時使用者需要經過使用者同意)。

您從 Google API Console取得的服務帳戶憑證會包含一組不重複的電子郵件地址、用戶端 ID,以及至少一個公開/私密金鑰組。您可以使用用戶端 ID 和一組私密金鑰來建立已簽署的 JWT,並以適當的格式建立存取憑證要求。接著,您的應用程式會向 Google OAuth 2.0 授權伺服器傳送憑證要求,該要求會傳回存取憑證。應用程式會使用這個權杖來存取 Google API。權杖到期時,應用程式會重複此程序。

您的伺服器應用程式使用 JWT 向 Google 授權伺服器要求憑證,然後使用該憑證呼叫 Google API 端點。不需要參與任何使用者。

詳情請參閱服務帳戶說明文件

權杖大小

權杖大小不一,但有下列限制:

  • 授權碼:256 個位元組
  • 存取憑證:2048 個位元組
  • 重新整理憑證:512 個位元組

Google Cloud 的 Security Token Service API 傳回的存取憑證與 Google API OAuth 2.0 存取憑證類似,但有不同的憑證大小限制。詳情請參閱 API 說明文件

Google 保留變更這些大小限制的權利,您的應用程式必須支援相應的變數大小。

重新整理憑證到期時間

您必須編寫程式碼,以預測授予的更新權杖可能無法正常運作。更新憑證可能會停止運作,原因如下:

  • 使用者已撤銷應用程式的存取權
  • 重新整理憑證已有 6 個月未使用。
  • 使用者變更密碼,而且更新憑證含有 Gmail 範圍。
  • 使用者帳戶的更新權杖數量已達上限 (即時)。
  • 使用者所屬的 Google Cloud Platform 機構已啟用工作階段控制政策。

Google Cloud Platform 專案設有針對外部使用者類型設定的 OAuth 同意畫面,且發布狀態為「測試」,並會在 7 天後核發更新憑證。

目前在每個 OAuth 2.0 用戶端 ID 中,每個 Google 帳戶最多只能有 50 個更新憑證。一旦達到上限,建立新的重新整理權杖會自動撤銷最舊的重新整理權杖,而不會發出任何警告。這項限制不適用於服務帳戶

另外,使用者帳戶或服務帳戶在各個用戶端的重新整理權杖總數也設有上限。多數一般使用者不會超過這項限制,但用於測試實作作業的開發人員帳戶可能會。

如果您需要授權多個程式、電腦或裝置,其中一種解決方法就是將每個 Google 帳戶授權的用戶端數量限制為 15 或 20 個。如果您是 Google Workspace 管理員,則可建立具備管理員權限的其他使用者,並對部分用戶端進行授權。

處理 Google Cloud Platform (GCP) 機構的工作階段控制政策

GCP 機構管理員在存取 GCP 資源時,可能需要使用 Google Cloud 工作階段控制功能,要求經常重新驗證。這項政策會影響存取 Google Cloud Console、Google Cloud SDK (也稱為 gcloud CLI) 以及任何需要 Cloud Platform 範圍的第三方 OAuth 應用程式。如果使用者在工作階段中設有工作階段控制政策,則工作階段持續時間到期時,您的 API 呼叫就會發生錯誤,且如果撤銷憑證遭到撤銷,就會發生類似錯誤;呼叫失敗時會顯示錯誤類型 invalid_token,這種子錯誤類型可用於區分撤銷憑證與工作階段控制政策導致的失敗。工作階段持續時間可能相當有限 (介於 1 小時至 24 小時之間),因此必須重新啟動驗證工作階段,以安全的方式處理這個狀況。

因此,您不得使用或鼓勵使用使用者憑證,以便進行伺服器對伺服器部署。如果將使用者憑證部署在伺服器上,用於長時間執行的工作或作業,而且客戶對這類使用者套用工作階段控制政策,則伺服器應用程式會失敗,因為工作階段持續時間結束後,您將無法重新驗證使用者。

要進一步瞭解如何協助客戶部署這項功能,請參閱這篇管理員提供的說明文章

用戶端程式庫

下列用戶端程式庫與熱門架構相互整合,因此導入 OAuth 2.0 變得更簡單了。我們會陸續在程式庫中新增更多功能。