Google API 使用 OAuth 2.0 通訊協定進行驗證及授權。Google 支援常見的 OAuth 2.0 情境,例如網路伺服器、用戶端、已安裝系統和有限輸入裝置應用程式等情境。
首先,從 Google API Console 取得 OAuth 2.0 用戶端憑證。接著,用戶端應用程式會向 Google 驗證伺服器要求存取權杖、從回應中擷取權杖,然後將權杖傳送至您要存取的 Google API。如需使用 Google 使用 OAuth 2.0 的互動式示範 (包括選擇使用自己的用戶端憑證),請嘗試使用 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 應用程式不需要密鑰,但網路伺服器應用程式卻可以。
您必須針對要執行應用程式的平台,建立適當的 OAuth 用戶端,例如:
- 伺服器端或 JavaScript 網頁應用程式會使用「網站」用戶端類型。請勿將此用戶端類型用於任何其他應用程式,例如原生或行動應用程式。
- 如果是 Android 應用程式,請使用「Android」用戶端類型。
- 如果是 iOS 和 macOS 應用程式,請使用「iOS」用戶端類型。
- 若為通用 Windows 平台應用程式,請使用「通用 Windows 平台」用戶端類型。
- 如果是部分輸入裝置 (例如電視或嵌入式裝置),請使用「電視和有限輸入裝置」用戶端類型。
- 如要進行伺服器對伺服器互動,請使用服務帳戶。
2. 從 Google 授權伺服器取得存取權杖。
您的應用程式必須先取得可供存取該 API 的存取權的存取權杖,才能使用 Google API 存取私人資料。單一存取權杖可以授予不同 API 存取權的不同程度。名為 scope
的變數參數會控制存取權杖允許的資源和作業組合。在存取權杖要求中,您的應用程式會在 scope
參數中傳送一或多個值。
提出這項要求的方法有很多種,實際方式則取決於您建構的應用程式類型。舉例來說,JavaScript 應用程式可能會透過瀏覽器重新導向至 Google 的存取權杖,但如果應用程式安裝在沒有瀏覽器服務的裝置上,便使用瀏覽器重新導向。
某些要求會要求使用者以 Google 帳戶登入。使用者登入後,系統會詢問使用者是否願意授予應用程式要求的一或多項權限。這項程序稱為使用者同意聲明。
如果使用者授予至少一項權限,Google 授權伺服器會將存取權杖 (或應用程式用於取得存取權杖的授權碼) 傳送給您的應用程式,以及該權杖所授予的存取權範圍清單。如果使用者並未授予權限,伺服器會傳回錯誤。
一般而言,最佳做法是要求在需要存取時間時才要求要求,而非事先要求。舉例來說,如果應用程式支援將活動儲存至日曆,則使用者必須先按下「新增至日曆」按鈕,Google 日曆存取權才能要求存取權;請參閱遞增授權。
3. 檢查使用者授予的存取權範圍。
將存取權杖回應中包含的範圍,與存取應用程式 Google 相關功能所需的範圍不同,這個範圍取決於相關 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。存取權杖到期後,應用程式會使用更新權杖來取得新的權杖。

詳情請參閱使用 OAuth 2.0 處理網路伺服器應用程式。
應用程式已安裝
Google OAuth 2.0 端點支援在電腦、行動裝置和平板電腦等裝置上安裝的應用程式。透過 Google API Console 建立用戶端 ID 時,請指定已安裝的應用程式,然後選取 Android、Chrome 應用程式、iOS、通用 Windows 平台 (UWP) 或電腦應用程式做為應用程式類型。
這項程序會產生用戶端 ID,在某些情況下,用戶端密鑰也會嵌入到應用程式原始碼中。(在這種情況下,用戶端密鑰看起來不會視為密鑰)。
應用程式將瀏覽器重新導向至 Google 網址時,授權序列就會開始;該網址會包含查詢參數,用於說明所要求的存取權類型。Google 會處理使用者驗證、工作階段選項和使用者同意聲明。結果是授權碼,應用程式可以交換存取權杖,以及更新權杖。
應用程式應儲存更新權杖供日後使用,並使用存取權杖存取 Google API。存取權杖到期後,應用程式會使用更新權杖來取得新的權杖。

詳情請參閱 針對已安裝的應用程式使用 OAuth 2.0。
用戶端 (JavaScript) 應用程式
Google OAuth 2.0 端點支援在瀏覽器中執行的 JavaScript 應用程式。
應用程式將瀏覽器重新導向至 Google 網址時,授權序列就會開始;該網址會包含查詢參數,用於說明所要求的存取權類型。Google 會處理使用者驗證、工作階段選項和使用者同意聲明。
結果是存取權杖,用戶端必須先驗證這個憑證,才能將權杖加入 Google API 要求。權杖到期後,應用程式會重複執行這個程序。

詳情請參閱針對用戶端應用程式使用 OAuth 2.0。
輸入受限裝置的應用程式
Google OAuth 2.0 端點支援在限定輸入裝置 (例如遊戲主機、攝影機和印表機) 上執行的應用程式。
授權序列是從應用程式向 Google 網址發出授權碼請求至 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。權杖到期後,應用程式會重複執行這個程序。

詳情請參閱 服務帳戶說明文件。
權杖大小
權杖的大小上限如下:
- 授權碼:256 個位元組
- 存取權杖:2048 個位元組
- 更新權杖:512 個位元組
Google Cloud 的 Security Token Service API 傳回的存取權杖結構類似 Google API OAuth 2.0 存取權杖,但權杖大小不同。詳情請參閱 API 說明文件。
Google 保留變更這些限制內權杖大小的權利,且您的應用程式必須能夠支援變化形式權杖大小。
更新權杖過期
您必須編寫程式碼,預計授予的更新權杖可能無法繼續運作。更新權杖可能會因為下列其中一項原因而停止運作:
- 使用者已撤銷應用程式的存取權。
- 這個更新權杖已有六個月。
- 使用者變更了密碼,更新權杖包含 Gmail 範圍。
- 使用者帳戶的授權 (即時) 更新權杖數量已達上限。
- 如果管理員
將應用程式範圍中要求的任何服務設為「受限制」 (錯誤為
admin_policy_enforced
)。 - 如果是 Google Cloud Platform API,管理員可能會設定工作階段長度。
如果 Google Cloud Platform 專案針對外部使用者類型設定 OAuth 同意畫面,且「發布測試」的發布狀態在 7 天後就會失效,除非要求的 OAuth 範圍是一組名稱、電子郵件地址和使用者個人資料 (透過
userinfo.email, userinfo.profile, openid
範圍或其 OpenID Connect 對等項目),否則系統會在 7 天後發出重新整理權杖。
每個 OAuth 2.0 用戶端 ID 目前每個 Google 帳戶最多只能更新 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
欄位可用於識別撤銷權杖,以及因工作階段控制政策 (例如 1 小時的 2 小時) 的失敗情形。"error_subtype": "invalid_rapt"
同樣地,您也不得使用或鼓勵使用使用者憑證來執行伺服器對伺服器部署作業。如果使用者在較長時間的工作或作業上部署使用者憑證,且客戶套用了工作階段控制政策,則伺服器應用程式將失敗,因為在工作階段持續時間結束時,不再重新驗證使用者。
如要進一步瞭解如何協助客戶部署這項功能,請參閱這篇管理員聚焦的說明文章。
用戶端程式庫
下列用戶端程式庫與熱門架構整合,方便您實作 OAuth 2.0。我們日後會新增更多程式庫。