Google API 使用 OAuth 2.0 通訊協定進行驗證及授權。Google 支援常見的 OAuth 2.0 情境，例如網路伺服器、用戶端、已安裝和輸入受限裝置應用程式。
首先，請前往 Google API 控制台取得 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 控制台取得 OAuth 2.0 憑證。
前往 Google API 控制台取得 OAuth 2.0 憑證，例如 Google 和應用程式都已知的用戶端 ID 和用戶端密鑰。這組值會因您建構的應用程式類型而異。舉例來說，JavaScript 應用程式不需要密鑰，但網路伺服器應用程式需要。
您必須建立適合應用程式執行平台的 OAuth 用戶端，例如：
- 如果是 Android 應用程式，請使用 Android 應用程式類型。
-
如果是 iOS 應用程式，請使用 iOS 應用程式類型。
- desktop_windows 如果是電腦版應用程式 (例如 Windows、macOS 或 Linux 應用程式或 CLI 工具)，請使用「電腦版應用程式」應用程式類型。
- code 如果是伺服器端或 JavaScript 網頁應用程式，請使用「網頁應用程式」應用程式類型。請勿將這個應用程式類型用於任何其他應用程式，例如原生或行動應用程式。
- chrome_extension 如果是 Chrome 擴充功能，請使用 Chrome 擴充功能應用程式類型。
- tv 如果是受限制的輸入裝置 (例如電視或嵌入式裝置)，請使用「電視和受限制的輸入裝置」應用程式類型。
- host 如要進行伺服器對伺服器互動，請使用服務帳戶。不需要 OAuth 用戶端 ID。
2. 從 Google 授權伺服器取得存取權杖。
應用程式必須先取得存取權杖，才能使用 Google API 存取私人資料。單一存取權杖可授予多個 API 不同程度的存取權。名為 scope 的變數參數可控制存取權杖允許的一組資源和作業。在存取權杖要求期間，應用程式會在 scope 參數中傳送一或多個值。
提出這項要求的方式有很多種，視您建構的應用程式類型而定。舉例來說，JavaScript 應用程式可能會使用瀏覽器重新導向至 Google 的方式要求存取權杖，而安裝在沒有瀏覽器的裝置上的應用程式則會使用網路服務要求。如要進一步瞭解如何提出要求，請參閱「Scenarios」和各應用程式類型的詳細導入指南。
部分要求需要使用者登入 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 參數名稱也是良好的 REST 做法。
存取權杖僅適用於權杖要求 scope 中所述的一組作業和資源。舉例來說，如果存取權杖是針對 Google 日曆 API 核發，就不會授予 Google 聯絡人 API 的存取權。不過，您可以多次將該存取權杖傳送至 Google 日曆 API，執行類似的操作。
5. 視需要重新整理存取權杖。
存取權杖的效期有限。如果應用程式需要存取 Google API 的時間超過單一存取權杖的效期，可以取得更新權杖。更新權杖可讓應用程式取得新的存取權杖。
情境
這些情境說明如何使用 OAuth 2.0 要求授權碼，以及取得不同類型應用程式的存取權杖和更新權杖。
網路伺服器應用程式
Google OAuth 2.0 端點支援使用 PHP、Java、Go、Python、Ruby 和 ASP.NET 等語言和架構的網路伺服器應用程式。
當應用程式將瀏覽器重新導向至 Google 網址時，授權程序就會開始；網址包含查詢參數，指出要求的存取權類型。Google 會處理使用者驗證、工作階段選取和使用者同意聲明。結果會是授權碼，應用程式可用來交換存取權杖和更新權杖。
應用程式應儲存更新權杖，以供日後使用，並使用存取權杖存取 Google API。存取權杖到期後，應用程式會使用更新權杖取得新的存取權杖。
詳情請參閱「使用 OAuth 2.0 處理網路伺服器應用程式」。
已安裝的應用程式
Google OAuth 2.0 端點支援安裝在電腦、行動裝置和平板電腦等裝置上的應用程式。透過 Google API 控制台建立用戶端 ID 時，請指定這是已安裝的應用程式，然後選取 Android、Chrome 擴充功能、iOS 或電腦版應用程式做為應用程式類型。
這項程序會產生用戶端 ID，有時也會產生用戶端密鑰，您必須將這些資訊嵌入應用程式的原始碼。(在這種情況下，用戶端密鑰顯然不會視為密鑰)。
當應用程式將瀏覽器重新導向至 Google 網址時，授權程序就會開始；網址包含查詢參數，指出要求的存取權類型。Google 會處理使用者驗證、工作階段選取和使用者同意聲明。結果會是授權碼，應用程式可用來交換存取權杖。應用程式應先驗證存取權杖，再將其納入 Google API 要求。權杖到期後，應用程式會重複上述程序。
後端伺服器也可以選擇將授權碼換成更新權杖，並儲存在安全的位置。存取權杖到期後，後端伺服器會使用更新權杖為應用程式取得新的存取權杖。
詳情請參閱 Android 的「授權存取 Google 使用者資料」、「在 iOS 應用程式中存取 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 API。存取權杖到期後，應用程式會使用更新權杖取得新的存取權杖。
詳情請參閱「針對裝置使用 OAuth 2.0」。
服務帳戶
Prediction API 和 Google Cloud Storage 等 Google API 可代表您的應用程式執行操作，而無須存取使用者資訊。在這種情況下，應用程式必須向 API 證明自己的身分，但不需要使用者同意。同樣地，在企業情境中，應用程式可以要求委派存取某些資源。
如要進行這類伺服器對伺服器互動，您需要服務帳戶，也就是屬於應用程式而非個別使用者的帳戶。您的應用程式會代表服務帳戶呼叫 Google API，因此不需要使用者同意。(在非服務帳戶情境中，應用程式會代表使用者呼叫 Google API，有時需要使用者同意)。
服務帳戶的憑證可從 Google API 控制台取得，包含一組產生的不重複電子郵件地址、一組用戶端 ID，以及至少一組公開/私密金鑰組。您可以使用用戶端 ID 和一個私密金鑰建立已簽署的 JWT，並以適當格式建構存取權杖要求。接著，應用程式會將權杖要求傳送至 Google OAuth 2.0 授權伺服器，伺服器會傳回存取權杖。應用程式會使用權杖存取 Google API。權杖到期後，應用程式會重複執行這項程序。
詳情請參閱 服務帳戶說明文件。
權杖大小
權杖大小不一，但不得超過下列限制：
Google Cloud 的 Security Token Service API 傳回的存取權杖結構與 Google API OAuth 2.0 存取權杖類似，但權杖大小限制不同。詳情請參閱 API 說明文件。
Google 保留在這些限制內變更權杖大小的權利，您的應用程式必須支援可變動的權杖大小。
更新權杖到期時間
編寫程式碼時，請務必考量到已授予的更新權杖可能失效。更新權杖可能因下列原因而失效：
如果 Google Cloud Platform 專案的 OAuth 同意畫面設定為外部使用者類型，且發布狀態為「測試中」，則系統會核發 7 天後到期的更新權杖，除非要求的 OAuth 範圍僅限名稱、電子郵件地址和使用者個人資料 (透過
userinfo.email, userinfo.profile, openid 範圍或其 OpenID Connect 對等項目)。
目前每個 Google 帳戶的每個 OAuth 2.0 用戶端 ID 最多可有 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 欄位可用於區分撤銷的權杖和因工作階段控制政策而失敗的情況 (例如 "error_subtype": "invalid_rapt")。由於工作階段持續時間可能非常有限 (介於 1 小時到 24 小時之間)，因此必須透過重新啟動驗證工作階段來妥善處理這種情況。
同樣地，您不得使用或鼓勵使用使用者憑證進行伺服器對伺服器部署。如果使用者憑證部署在伺服器上，用於長時間執行的工作或作業，且客戶對這類使用者套用工作階段控制政策，伺服器應用程式就會失敗，因為工作階段持續時間到期時，系統無法重新驗證使用者。
如要進一步瞭解如何協助客戶部署這項功能，請參閱這篇管理員專用說明文章。
用戶端程式庫
下列用戶端程式庫與熱門架構整合，可簡化 OAuth 2.0 的實作。我們日後會陸續新增更多功能。