Google致力於提高黑人社區的種族平等。 怎麼看。

使用 OAuth 2.0 訪問 Google API

谷歌的API使用的OAuth 2.0協議進行身份驗證和授權。 Google 支持常見的 OAuth 2.0 方案,例如用於 Web 服務器、客戶端、已安裝和有限輸入設備應用程序的方案。

首先,獲得來自OAuth 2.0用戶憑據 Google API Console 。然後,您的客戶端應用程序從 Google 授權服務器請求訪問令牌,從響應中提取令牌,並將令牌發送到您要訪問的 Google API。對於使用OAuth 2.0與谷歌的互動演示(包括利用自己的客戶端證書的選項),實驗用的OAuth 2.0遊樂場

此頁面概述了 Google 支持的 OAuth 2.0 授權方案,並提供了指向更詳細內容的鏈接。有關使用OAuth 2.0認證的詳細信息,請參閱ID連接

基本步驟

所有應用程序在使用 OAuth 2.0 訪問 Google API 時都遵循基本模式。在較高級別上,您可以執行以下五個步驟:

1.獲取的OAuth從2.0憑據 Google API Console。

訪問 Google API Console獲得OAuth 2.0憑據,如已知為谷歌和你的應用程序客戶端ID和客戶端密鑰。這組值因您正在構建的應用程序類型而異。例如,JavaScript 應用程序不需要密碼,但 Web 服務器應用程序需要。

2. 從谷歌授權服務器獲取訪問令牌。

在您的應用程序可以使用 Google API 訪問私有數據之前,它必須獲得授予對該 API 訪問權限的訪問令牌。單個訪問令牌可以授予對多個 API 不同程度的訪問權限。一種可變參數調用scope控制所述一組資源和操作的,一個訪問令牌許可證。在訪問令牌請求,你的應用程序中發送一個或多個值scope參數。

有多種方法可以發出此請求,它們因您正在構建的應用程序類型而異。例如,JavaScript 應用程序可能使用瀏覽器重定向到 Google 來請求訪問令牌,而安裝在沒有瀏覽器的設備上的應用程序使用 Web 服務請求。

某些請求需要用戶使用其 Google 帳戶登錄的身份驗證步驟。登錄後,系統會詢問用戶是否願意授予您的應用程序請求的一項或多項權限。這個過程被稱為用戶的同意

如果用戶授予了至少一項權限,Google 授權服務器會向您的應用程序發送一個訪問令牌(或您的應用程序可用於獲取訪問令牌的授權代碼)以及該令牌授予的訪問範圍列表。如果用戶未授予權限,服務器將返回錯誤。

通常最佳做法是在需要訪問時增量請求範圍,而不是預先請求。例如,想要支持將事件保存到日曆的應用程序在用戶按下“添加到日曆”按鈕之前不應請求訪問 Google 日曆;看到增量授權

3. 檢查用戶授予的訪問範圍。

將訪問令牌響應中包含的範圍與訪問依賴於相關 Google API 的應用程序的特性和功能所需的範圍進行比較。禁用無法訪問相關 API 的應用程序的任何功能。

您的請求中包含的範圍可能與您的響應中包含的範圍不匹配,即使用戶授予了所有請求的範圍。有關訪問所需的範圍,請參閱每個 Google API 的文檔。 API 可以將多個範圍字符串值映射到單個訪問範圍,為請求中允許的所有值返回相同的範圍字符串。例:谷歌API的人可能返回的範圍https://www.googleapis.com/auth/contacts當一個應用程序要求用戶授權的範圍https://www.google.com/m8/feeds/ ;谷歌的API人們方法people.updateContact需要的授予範圍https://www.googleapis.com/auth/contacts

4. 將訪問令牌發送到 API。

後的應用程序獲得的訪問令牌時,它發送該令牌在谷歌的API HTTP授權請求頭。可以將令牌作為 URI 查詢字符串參數發送,但我們不建議這樣做,因為 URI 參數最終可能會出現在不完全安全的日誌文件中。此外,避免創建不必要的 URI 參數名稱也是一種很好的 REST 實踐。請注意,查詢字符串支持將於 2021 年 6 月 1 日棄用。

訪問令牌的有效期只為集所描述的操作和資源的scope令牌請求。例如,如果為 Google Calendar API 頒發了訪問令牌,則它不會授予對 Google Contacts API 的訪問權限。但是,您可以多次將該訪問令牌發送到 Google 日曆 API 以進行類似操作。

5. 如有必要,刷新訪問令牌。

訪問令牌的生命週期有限。如果您的應用程序需要在單個訪問令牌的生命週期之外訪問 Google API,它可以獲取刷新令牌。刷新令牌允許您的應用程序獲取新的訪問令牌。

場景

網絡服務器應用程序

Google OAuth 2.0 端點支持使用 PHP、Java、Python、Ruby 和 ASP.NET 等語言和框架的 Web 服務器應用程序。

當您的應用程序將瀏覽器重定向到 Google URL 時,授權序列就開始了; URL 包含指示所請求訪問類型的查詢參數。 Google 處理用戶身份驗證、會話選擇和用戶同意。結果是一個授權代碼,應用程序可以用它來交換訪問令牌和刷新令牌。

應用程序應存儲刷新令牌以備將來使用,並使用訪問令牌訪問 Google API。一旦訪問令牌過期,應用程序將使用刷新令牌來獲取新令牌。

您的應用程序向 Google 授權服務器發送令牌請求,接收授權代碼,交換令牌代碼,並使用令牌調用 Google API 端點。

有關詳細信息,請參閱使用OAuth 2.0 Web服務器應用程序

已安裝的應用程序

Google OAuth 2.0 端點支持安裝在計算機、移動設備和平板電腦等設備上的應用程序。當您創建通過客戶端ID Google API Console ,指定這是已安裝的應用程序,然後選擇的Android,Chrome應用,iOS版,通用的Windows平台(UWP),或桌面應用作為應用程序類型。

該過程會生成一個客戶端 ID,在某些情況下還會生成一個客戶端機密,您將其嵌入到應用程序的源代碼中。 (在這種情況下,客戶端機密顯然不被視為機密。)

當您的應用程序將瀏覽器重定向到 Google URL 時,授權序列就開始了; URL 包含指示所請求訪問類型的查詢參數。 Google 處理用戶身份驗證、會話選擇和用戶同意。結果是一個授權代碼,應用程序可以用它來交換訪問令牌和刷新令牌。

應用程序應存儲刷新令牌以備將來使用,並使用訪問令牌訪問 Google API。一旦訪問令牌過期,應用程序將使用刷新令牌來獲取新令牌。

您的應用程序向 Google 授權服務器發送令牌請求,接收授權代碼,交換令牌代碼,並使用令牌調用 Google API 端點。

有關詳細信息,請參閱使用OAuth 2.0安裝的應用程序

客戶端 (JavaScript) 應用程序

Google OAuth 2.0 端點支持在瀏覽器中運行的 JavaScript 應用程序。

當您的應用程序將瀏覽器重定向到 Google URL 時,授權序列就開始了; URL 包含指示所請求訪問類型的查詢參數。 Google 處理用戶身份驗證、會話選擇和用戶同意。

結果是訪問令牌,客戶端應在將其包含在 Google API 請求中之前對其進行驗證。當令牌過期時,應用程序重複該過程。

您的 JS 應用程序向 Google 授權服務器發送令牌請求、接收令牌、驗證令牌並使用令牌調用 Google API 端點。

有關詳細信息,請參閱使用OAuth 2.0客戶端應用程序

在有限輸入設備上的應用

Google OAuth 2.0 端點支持在有限輸入設備(例如游戲機、攝像機和打印機)上運行的應用程序。

授權序列從應用程序向 Google URL 發出 Web 服務請求以獲取授權代碼開始。響應包含多個參數,包括 URL 和應用程序向用戶顯示的代碼。

用戶從設備獲取 URL 和代碼,然後切換到具有更豐富輸入功能的單獨設備或計算機。用戶啟動瀏覽器,導航到指定的 URL,登錄並輸入代碼。

同時,應用程序以指定的時間間隔輪詢 Google URL。用戶批准訪問後,來自 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 字節

訪問由谷歌Cloud的返回的標記安全令牌服務API的結構類似於谷歌API的OAuth 2.0訪問令牌,但有不同的令牌大小限制。有關詳細信息,請參閱API文檔

Google 保留在這些限制內更改令牌大小的權利,並且您的應用程序必須相應地支持可變的令牌大小。

刷新令牌過期

您必須編寫代碼以預測授予的刷新令牌可能不再起作用的可能性。由於以下原因之一,刷新令牌可能會停止工作:

  • 用戶已經撤銷你的應用程序的訪問
  • 刷新令牌已六個月未使用。
  • 用戶更改了密碼,刷新令牌包含 Gmail 範圍。
  • 用戶帳戶已超過授予(實時)刷新令牌的最大數量。
  • 用戶屬於具有有效會話控制策略的 Google Cloud Platform 組織。

為外部用戶類型配置了 OAuth 同意屏幕且發布狀態為“測試”的 Google Cloud Platform 項目會收到一個刷新令牌,該令牌將在 7 天后到期。

目前,每個 OAuth 2.0 客戶端 ID 每個 Google 帳戶的刷新令牌限制為 50 個。如果達到限制,則創建新的刷新令牌會自動使最舊的刷新令牌無效,而不會發出警告。此限制並不適用於服務帳戶

用戶帳戶或服務帳戶在所有客戶端上可以擁有的刷新令牌總數也有更大的限制。大多數普通用戶不會超過此限制,但用於測試實現的開發人員帳戶可能會超過此限制。

如果您需要授權多個程序,機器或設備,一個解決辦法是限制你每個谷歌賬戶授權給15或20。如果你是一個客戶端的數量谷歌工作區管理員,您可以創建具有管理權限,其他用戶使用它們來授權一些客戶端。

處理 Google Cloud Platform (GCP) 組織的會話控制策略

而他們訪問GCP資源GCP組織的管理員可能需要用戶頻繁重認證,使用谷歌雲會話控制功能。此政策影響訪問谷歌雲端控制台中,谷歌雲SDK (又稱gcloud CLI),這需要雲平台範圍內的任何第三方OAuth應用。如果用戶擁有代替會話控制政策,然後在會話持續時間屆滿後,你的API調用時會報錯了類似令牌是否被撤銷的刷新會發生什麼-電話將錯誤類型失敗invalid_token ;子錯誤類型可用於區分撤銷令牌和由於會話控制策略導致的失敗。由於會話持續時間可能非常有限(在 1 小時到 24 小時之間),因此必須通過重新啟動身份驗證會話來妥善處理這種情況。

同樣,您不得使用或鼓勵使用用戶憑據進行服務器到服務器部署。如果用戶憑據部署在服務器上用於長時間運行的作業或操作,並且客戶對此類用戶應用會話控制策略,則服務器應用程序將失敗,因為在會話持續時間到期時將無法重新驗證用戶。

有關如何幫助客戶部署此功能的更多信息,請參見本管理為重點的幫助文章。

客戶端庫

以下客戶端庫與流行的框架集成,這使得實現 OAuth 2.0 更簡單。隨著時間的推移,更多功能將添加到庫中。