使用 OAuth 2.0 存取 Google API

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

如要開始操作,請透過 Google API Console 取得 OAuth 2.0 用戶端憑證。接著,您的用戶端應用程式會向 Google 授權伺服器要求存取權杖、從回應中擷取權杖,然後將權杖傳送至您要存取的 Google API。如需 OAuth 2.0 與 Google 搭配使用的互動式示範 (包括使用自己的用戶端憑證選項),請試用 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 應用程式不需要密鑰,但網路伺服器應用程式會。

您必須針對執行應用程式的平台建立適當的 OAuth 用戶端,例如:

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 授權要求標頭將權杖傳送至 Google API。您可以將權杖以 URI 查詢字串參數傳送,但我們不建議這麼做,因為 URI 參數最終可能位於不安全的記錄檔中。此外,建議您採用 REST 方式,避免建立不必要的 URI 參數名稱。

存取權杖僅適用於權杖要求 scope 中所述的一組作業和資源。舉例來說,如果您為 Google Calendar API 核發了存取權杖,就不會授予 Google Contacts API 的存取權。不過,您可以多次將存取權杖傳送至 Google Calendar API 來進行類似作業。

5. 必要時,請重新整理存取權杖。

存取權杖的生命週期有限。如果您的應用程式在單一存取權杖的生命週期之外需要存取 Google API,就可以獲得更新權杖。更新權杖可讓應用程式取得新的存取權杖。

情境

網路伺服器應用程式

Google OAuth 2.0 端點支援使用語言和架構 (例如 PHP、Java、Go、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 平台」(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

服務帳戶

預測 API 和 Google Cloud Storage 等 Google API 可以代表您的應用程式執行動作,而且無須存取使用者資訊。在這類情況下,應用程式需要向 API 證明自己的身分,但不需要使用者同意。同樣地,在企業情境中,應用程式也可以要求某些資源的委派存取權。

針對這些類型的伺服器對伺服器互動,您必須具備「服務帳戶」,該帳戶屬於應用程式,而非個別使用者的帳戶。您的應用程式會代表服務帳戶呼叫 Google API,因此不需要取得使用者同意。(在非服務帳戶情境中,您的應用程式會代表使用者呼叫 Google API,有時需要使用者同意)。

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

您的伺服器應用程式會透過 JWT 向 Google 授權伺服器要求權杖,然後使用該權杖呼叫 Google API 端點。不會涉及使用者。

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

權杖大小

權杖大小可能不同,但有以下限制:

  • 授權碼:256 個位元組
  • 存取權杖:2,048 個位元組
  • 重新整理符記:512 個位元組

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

Google 保留在此限制內變更權杖大小的權利,且您的應用程式必須支援變數權杖大小。

重新整理權杖過期

您必須編寫程式碼,預測授予的更新權杖可能無法再運作的可能性。更新權杖可能因為下列其中一個原因而停止運作:

除非要求的 OAuth 範圍是名稱、電子郵件地址和使用者個人資料的子集 (透過 userinfo.email, userinfo.profile, openid 範圍或其 OpenID Connect 對等項目),否則如果 Google Cloud Platform 專案的 OAuth 同意畫面已設定為外部使用者類型且發布狀態為「測試」,系統就會在 7 天後核發更新權杖。

每個 Google 帳戶目前每個 OAuth 2.0 用戶端 ID 最多只能有 100 個更新權杖。達到上限後,一旦建立新的更新權杖,最舊的更新權杖就會自動失效,且系統不會發出警告。這項限制不適用於服務帳戶

另外,使用者帳戶或服務帳戶在所有用戶端中的更新權杖總數也設有上限。多數一般使用者不會超過此上限,但用來測試實作的開發人員帳戶可能會超過此上限。

如果您需要授權多個程式、機器或裝置,可以採用其中一種解決方法,將每個 Google 帳戶授權的用戶端數量限制為 15 或 20 個。如果您是 Google Workspace 管理員,可以建立具有管理員權限的其他使用者,並用於授權部分用戶端。

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

GCP 機構的管理員可能需要在存取 GCP 資源時,使用 Google Cloud 工作階段控制功能,頻繁地重新驗證使用者。這項政策會影響對 Google Cloud 控制台、Google Cloud SDK (也稱為 gcloud CLI) 的存取權,以及任何需要 Cloud Platform 範圍的第三方 OAuth 應用程式。如果使用者已採用工作階段控制政策,則在工作階段持續時間到期時,API 呼叫就會發生錯誤,類似重新整理權杖遭撤銷後會發生的情況。呼叫將會失敗,並傳回錯誤類型 invalid_grant;可用來區分因工作階段控制政策而遭撤銷的權杖和失敗情形 (例如工作階段控制政策在 4 小時內必須維持極限)。error_subtype"error_subtype": "invalid_rapt"

同理,您不得使用或鼓勵使用使用者憑證進行伺服器對伺服器部署作業。假如使用者憑證是針對長時間執行的工作或作業部署在伺服器上,且客戶對此類使用者套用工作階段控制政策,則伺服器應用程式將會失敗,因為在工作階段持續時間到期後,就無法重新驗證使用者。

如要進一步瞭解如何協助客戶部署這項功能,請參閱由管理員特別撰寫的說明文章

用戶端程式庫

下列用戶端程式庫已與熱門架構整合,可讓您更輕鬆地實作 OAuth 2.0。日後我們會陸續在程式庫中新增更多功能。