使用 OAuth 2.0 存取 Google API

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

首先，請從 取得 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. 從 取得 OAuth 2.0 憑證。

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

您必須建立適合應用程式執行平台的 OAuth 用戶端，例如：

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

應用程式必須先取得可授予該 API 存取權的存取權杖，才能使用 Google API 存取私人資料。單一存取權杖可授予多個 API 不同程度的存取權。名為 scope 的變數參數會控管存取權存取權杖允許的資源和作業組合。在存取權權杖要求期間，應用程式會在 scope 參數中傳送一或多個值。

您可以透過多種方式提出這項要求，具體方式取決於您要建構的應用程式類型。舉例來說，JavaScript 應用程式可能會使用瀏覽器重新導向至 Google 的做法，要求存取權權杖，而安裝在沒有瀏覽器的裝置上的應用程式則會使用網頁服務要求。

部分要求需要驗證步驟，使用者必須透過 Google 帳戶登入。登入後，系統會詢問使用者是否願意授予應用程式要求的一或多項權限。這項程序稱為「使用者同意」。

如果使用者至少授予一項權限，Google 授權伺服器就會傳送存取權杖 (或應用程式可用來取得存取權杖的授權碼)，以及該權杖授予的存取權範圍清單給應用程式。如果使用者未授予權限，伺服器會傳回錯誤。

一般來說，最佳做法是在需要存取權時，逐步要求範圍，而非一開始就要求。舉例來說，如果應用程式想要支援將活動儲存至日曆，則應在使用者按下「Add to Calendar」(新增至日曆) 按鈕後，才要求 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 參數名稱，也是良好的 REST 做法。

存取權存取權杖僅適用於權杖要求的 scope 中所述的作業和資源組合。舉例來說，如果存取權權杖是針對 Google 日曆 API 核發，則不會授予 Google 聯絡人 API 的存取權。不過，您可以將該存取權杖多次傳送至 Google 日曆 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 端點支援在電腦、行動裝置和平板電腦等裝置上安裝的應用程式。透過 建立用戶端 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 處理裝置」。

服務帳戶

Google API (例如 Prediction API 和 Google Cloud Storage) 可代表您的應用程式執行操作，但不必存取使用者資訊。在這種情況下，您的應用程式需要向 API 證明自身身分，但不需要使用者同意。同樣地，在企業情境中，應用程式可以要求對某些資源的委派存取權。

針對這類伺服器對伺服器互動，您需要使用服務帳戶，這是屬於應用程式，而非個別使用者的帳戶。應用程式會代表服務帳戶呼叫 Google API，且不需要使用者同意。(在非服務帳戶的情況下，應用程式會代表使用者呼叫 Google API，因此有時需要使用者同意)。

您從 取得的服務帳戶憑證，包括產生的專屬電子郵件地址、客戶端 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 等價)。

目前每個 Google 帳戶和 OAuth 2.0 用戶端 ID 的更新權杖數量上限為 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 小時至 24 小時之間)，因此必須重新啟動驗證工作階段，才能妥善處理此情況。

同樣地，您不得使用或鼓勵使用者在伺服器對伺服器部署作業中使用憑證。如果使用者憑證部署在伺服器上，用於長時間執行的工作或作業，而客戶對這類使用者套用工作階段控制政策，由於在工作階段時間到期時無法重新驗證使用者，因此伺服器應用程式會失敗。

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

用戶端程式庫

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