使用 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 應用程式不需要密鑰,但網路伺服器應用程式卻不需要。

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

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

這項要求的傳送方式有很多種,並視您建構的應用程式類型而有所不同。舉例來說,JavaScript 應用程式可能會使用瀏覽器重新導向功能,要求存取存取憑證,而安裝在沒有瀏覽器的裝置上,應用程式則使用網路服務要求。

某些要求會要求驗證使用者必須使用自己的 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、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

服務帳戶

如 Prediction 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 保留變更權杖大小限制的權利,您的應用程式必須支援可變的權杖大小。

重新整理權杖到期時間

您必須編寫程式碼,預期已授予的重新整理權杖可能無法正常運作。更新權杖可能會停止運作,原因如下:

  • 使用者已撤銷應用程式的存取權
  • 重新整理憑證已連續六個月未使用。
  • 使用者變更密碼且更新權杖包含 Gmail 範圍。
  • 使用者帳戶已超過更新 (即時) 的更新憑證上限。
  • 使用者所屬的 Google Cloud Platform 機構已設定工作階段控制政策。

Google Cloud Platform 專案的 OAuth 同意畫面已設定為外部使用者類型,發布狀態則為「測試中」,因此系統會發出更新憑證,該憑證將於 7 天後失效。

目前每個 OAuth 2.0 用戶端 ID 的 Google 帳戶最多只能更新 100 個重新整理憑證。達到上限後,建立新的重新整理權杖會自動失效最舊的重新整理權杖,而不顯示警告。這項限制不適用於服務帳戶

使用者帳戶或服務帳戶可在所有用戶端上擁有的重新整理權杖總數有上限。大多數一般使用者不會超過此上限,但用來測試實作作業的開發人員帳戶可能會。

如果您需要授權多個程式、機器或裝置,其中一個解決方法是將每個 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 的實作。我們會陸續為資料庫新增更多功能。