使用 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 參數可能會位於並不安全的記錄檔中。此外，我們也建議您避免建立不必要的 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。

服務帳戶

例如，Predict 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 位元組
  • 存取權杖：2048 個位元組
  • 更新權杖：512 個位元組

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

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

更新權杖到期日

您必須編寫程式碼，預期授予的更新權杖可能會失效。下列其中一種原因可能會導致更新權杖停止運作：

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

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

使用者帳戶或服務帳戶在所有用戶端可擁有的更新權杖總數也較大。大多數一般使用者不會超過這項限制，但可以透過開發人員帳戶測試實作作業。

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

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

GCP 機構的管理員可能在使用 Google Cloud 工作階段控制功能時，要求在存取 GCP 資源時頻繁重新驗證使用者。這項政策會影響 Google Cloud 控制台、Google Cloud SDK (也稱為 gcloud CLI)，以及任何需要 Cloud Platform 範圍的第三方 OAuth 應用程式的存取權。如果使用者設有工作階段控制政策，則在工作階段持續時間到期時，您的 API 呼叫會發出類似的錯誤，類似於更新權杖遭到撤銷時會發生的情況。呼叫會失敗並顯示錯誤類型 invalid_grant；您可以使用 error_subtype 欄位區分憑證撤銷和因工作階段控制政策重新啟動而失敗的情況 (例如 "error_subtype": "invalid_rapt")。由於工作階段驗證會在 1 小時內完全以寬限期 (例如 "error_subtype": "invalid_rapt") 處理，因此必須在 1 小時內以安全的方式處理工作階段。

同樣地，我們也不得使用或鼓勵使用使用者憑證進行伺服器對伺服器部署作業。假如使用者憑證已部署於伺服器上，進行長時間執行的工作或作業，且客戶對這類使用者套用工作階段控制政策，伺服器應用程式就會失敗，因為工作階段持續時間到期時無法重新驗證使用者。

如要進一步瞭解如何協助客戶部署這項功能，請參閱這篇由管理員主導的說明文章。

用戶端程式庫

下列用戶端程式庫已與熱門架構整合，方便您實作 OAuth 2.0。我們會陸續在程式庫中新增更多功能。