Google致力於提高黑人社區的種族平等。 怎麼看。
本頁面由 Cloud Translation API 翻譯而成。
Switch to English

使用OAuth 2.0訪問Google API

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

首先,請從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應用程序不需要密碼,而Web服務器應用程序則需要密碼。

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

在您的應用程序可以使用Google API訪問私有數據之前,它必須獲取一個授予該API訪問權限的訪問令牌。單個訪問令牌可以授予對多個API的不同程度的訪問。名為scope的變量參數控制訪問令牌允許的資源和操作的集合。在訪問令牌請求期間,您的應用程序將在scope參數中發送一個或多個值。

發出此請求的方法有幾種,並且根據您所構建的應用程序的類型而有所不同。例如,JavaScript應用程序可能會使用瀏覽器重定向到Google來請求訪問令牌,而安裝在沒有瀏覽器的設備上的應用程序會使用網絡服務請求。

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

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

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

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

將訪問令牌響應中包含的範圍與根據對相關Google API的訪問來訪問應用程序功能所需的範圍進行比較。禁用您的應用程序的所有功能,這些功能在無法訪問相關API的情況下無法運行。

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

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

應用程序獲取訪問令牌後,會將令牌發送到HTTP授權請求標頭中的Google API。可以將令牌作為URI查詢字符串參數發送,但是我們不建議這樣做,因為URI參數可能最終存儲在不完全安全的日誌文件中。另外,避免創建不必要的URI參數名稱也是REST的良好做法。請注意,查詢字符串支持將於2021年6月1日棄用。

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

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

訪問令牌的壽命有限。如果您的應用程序需要在單個訪問令牌的生存期之外訪問Google API,則可以獲取刷新令牌。刷新令牌使您的應用程序可以獲得新的訪問令牌。

情境

Web服務器應用程序

Google OAuth 2.0終結點支持使用諸如PHP,Java,Python,Ruby和ASP.NET之類的語言和框架的Web服務器應用程序。

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

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

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

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

已安裝的應用程序

Google OAuth 2.0終結點支持在計算機,移動設備和平板電腦等設備上安裝的應用程序。通過Google API Console創建客戶端ID時,請指定這是已安裝的應用程序,然後選擇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

服務帳號

諸如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保留在這些限制內更改令牌大小的權利,並且您的應用程序必須相應地支持可變的令牌大小。

刷新令牌到期

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

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

具有為外部用戶類型配置的OAuth同意屏幕且發布狀態為“測試”的Google Cloud Platform項目的刷新令牌將在7天后過期。

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

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

如果您需要授權多個程序,機器或設備,一種解決方法是將每個Google帳戶授權的客戶端數量限制為15或20。如果您是Google Workspace管理員,則可以創建具有管理權限的其他用戶,並使用它們來授權一些客戶。

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

GCP組織的管理員可能需要使用Google Cloud會話控制功能在用戶訪問GCP資源時進行頻繁的重新認證此政策會影響對Google Cloud Console,google cloud SDK(也稱為gcloud CLI)和需要Cloud Platform作用域的任何第三方OAuth應用程序的訪問。如果用戶具有會話控制策略,則在會話持續時間到期時,您的API調用將出錯,類似於撤銷刷新令牌時將發生的錯誤。由於會話持續時間可能非常有限(介於1小時至24小時之間),因此必須通過重新啟動身份驗證會話來妥善處理此情況。

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

有關如何幫助您的客戶部署此功能的更多信息,請參閱此以管理員為中心的幫助文章。

客戶端庫

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