使用 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 授權伺服器取得存取權杖。

應用程式必須先取得授予存取權給該 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、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 機構已設定工作階段控制政策。

設定 OAuth 同意畫面的 Google Cloud Platform 專案,用於外部使用者類型及發布狀態設為「測試」,因此發布更新權杖將於 7 天後失效。

目前每個 OAuth 2.0 用戶端 ID 的每個 Google 帳戶最多只能有 100 個重新整理權杖。如果已達到上限,則建立新的重新整理權杖會自動失效最舊的重新整理權杖,而不會發出警告。這項限制不適用於服務帳戶

使用者帳戶或服務帳戶在所有用戶端中的整體重新整理權杖數量也有上限。多數一般使用者不會超過這項限制,但用來測試實作結果的開發人員帳戶可能會有問題。

如果您需要授權多個程式、電腦或裝置,其中一個解決方法是將每個 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 呼叫會發生錯誤,如撤銷更新權杖會有什麼結果;呼叫因錯誤類型 invalid_token 而失敗;子錯誤類型可用於區分因工作階段控制政策而撤銷的權杖和失敗。由於工作階段持續時間可能有限 (介於 1 小時到 24 小時之間),因此您必須重新啟動驗證工作階段來妥善處理這種情況。

同樣地,您不得使用或鼓勵使用使用者憑證來進行伺服器對伺服器部署作業。如果使用者伺服器部署於長時間執行的工作或作業,且客戶對這類使用者套用工作階段控制政策,則伺服器工作階段會失敗,因為工作階段持續時間結束時,使用者將無法重新驗證使用者。

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

用戶端程式庫

下列用戶端程式庫與常見的架構整合,可簡化 OAuth 2.0 的導入作業。我們會陸續為資料庫新增更多功能。