跳至主要內容

設定 Google 社交登入

整合 Google OAuth 2.0 驗證 (Authentication) 系統，啟用 Google 登入、帳號連結，以及安全存取 Google API。

提示:

本指南假設你已對 Logto 連接器 (Connectors) 有基本了解。若不熟悉，請參閱 連接器 (Connectors) 指南以開始使用。

開始使用​

Google 連接器 (Connector) 支援 OAuth 2.0 整合，讓你的應用程式可以：

  • 新增「使用 Google 登入」驗證 (Authentication)
  • 將使用者帳號與 Google 身分連結
  • 從 Google 同步使用者個人資料資訊
  • 透過 Logto Secret Vault 安全儲存權杖，存取 Google API 以自動化任務（例如：編輯 Google 文件、在你的應用程式中管理行事曆事件）

要設定這些驗證 (Authentication) 功能，請先在 Logto 建立 Google 連接器 (Connector)：

  1. 前往 Logto 控制台 > 連接器 (Connector) > 社交連接器 (Social connector)。
  2. 點擊 新增社交連接器，選擇 Google，點擊 下一步，並依照分步教學完成整合。

步驟 1：在 Google Auth Platform 建立專案​

在你能將 Google 作為驗證 (Authentication) 提供者之前，必須先在 Google Cloud Console 建立專案以取得 OAuth 2.0 憑證。如果你已有專案，可跳過此步驟。

  1. 前往 Google Cloud Console 並使用你的 Google 帳戶登入。
  2. 點擊頂部選單列的 選擇專案（Select a project） 按鈕，然後點擊 新增專案（New Project） 以建立專案。
  3. 在新建立的專案中，前往 API 與服務 > OAuth 同意畫面（APIs & Services > OAuth consent screen） 來設定你的應用程式：
    • 應用程式資訊（App information）：輸入要顯示於同意頁面的 應用程式名稱（Application name） 與 支援電子郵件（Support email）
    • 受眾（Audience）：選擇你偏好的受眾類型：
      • 內部（Internal） - 僅限你組織內的 Google Workspace 使用者
      • 外部（External） - 任何 Google 使用者皆可（正式上線需驗證）
    • 聯絡資訊（Contact information）：提供電子郵件地址，讓 Google 能通知你專案的任何變更
    • 勾選 我同意 Google 的政策（I agree to Google's policies） 完成基本設定
  4. （選填）前往 品牌設定（Branding） 區段，編輯產品資訊並上傳你的 應用程式標誌（App logo），該標誌將顯示於 OAuth 同意頁面，協助使用者辨識你的應用程式。
提示:

如果你選擇 外部（External） 受眾類型，開發期間需新增測試使用者，並於正式上線時發佈應用程式。

步驟 2：建立 OAuth 2.0 憑證​

在 Google Cloud Console 的 憑證（Credentials） 頁面，為你的應用程式建立 OAuth 憑證。

  1. 點擊 建立憑證（Create Credentials）> OAuth 用戶端 ID（OAuth client ID）。
  2. 選擇 網頁應用程式（Web application） 作為應用程式類型。
  3. 填寫 OAuth 用戶端的 名稱（Name）。這僅用於識別憑證，不會顯示給終端使用者。
  4. 設定授權的 URI：
    • 授權的 JavaScript 來源（Authorized JavaScript origins）：新增你的 Logto 實例來源（例如 https://your-logto-domain.com）
    • 授權的重新導向 URI（Authorized redirect URIs）：新增 Logto 的 Callback URI（可從 Logto Google 連接器複製）
  5. 點擊 建立（Create） 以產生 OAuth 用戶端。

步驟 3：用憑證設定 Logto 連接器​

建立 OAuth 用戶端後，Google 會顯示一個包含憑證的視窗：

  1. 複製 Client ID 並貼到 Logto 的 clientId 欄位
  2. 複製 Client secret 並貼到 Logto 的 clientSecret 欄位
  3. 在 Logto 點擊 儲存並完成（Save and Done），即可將你的身分系統與 Google 連接
注意:

請妥善保管你的 client secret，切勿在前端程式碼中暴露。如果洩漏，請立即產生新密鑰。

步驟 4：設定權限範圍（Scopes）​

權限範圍（Scopes）定義你的應用程式向使用者請求哪些權限，並控制可從其 Google 帳戶存取哪些資料。

在 Google Cloud Console 設定權限範圍​

  1. 前往 API 與服務 > OAuth 同意畫面 > 權限範圍（APIs & Services > OAuth consent screen > Scopes）。
  2. 點擊 新增或移除權限範圍（Add or Remove Scopes），僅選擇應用程式所需的權限範圍：
    • 驗證 (Authentication)（必要）：
      • https://www.googleapis.com/auth/userinfo.email
      • https://www.googleapis.com/auth/userinfo.profile
      • openid
    • API 存取（選填）：根據應用程式需求新增其他權限範圍（如 Drive、Calendar、YouTube）。可瀏覽 Google API Library 查找可用服務。若需存取進階 Google API，請先在 Google API Library 啟用對應 API（如 Google Drive API、Gmail API、Calendar API）。
  3. 點擊 更新（Update） 確認選擇。
  4. 點擊 儲存並繼續（Save and Continue） 套用變更。

在 Logto 設定權限範圍​

根據需求選擇以下其中一種方式：

選項 1：不需額外 API 權限範圍

  • 保持 Logto Google 連接器的 Scopes 欄位為空。
  • 預設會請求 openid profile email 權限範圍，確保 Logto 能正確取得基本使用者資訊。

選項 2：登入時請求額外權限範圍

  • 在 Scopes 欄位輸入所有所需權限範圍，以空格分隔。
  • 此處填寫的權限範圍會覆蓋預設值，因此請務必包含驗證 (Authentication) 權限範圍：https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid。
  • 請使用完整的權限範圍 URL。例如：https://www.googleapis.com/auth/calendar.readonly。

選項 3：後續漸進式請求權限範圍

  • 使用者登入後，可透過重新啟動聯邦社交授權流程並更新使用者的權杖組，按需請求額外權限範圍。
  • 這些額外權限範圍無需預先填寫在 Logto Google 連接器的 Scopes 欄位，可透過 Logto 的 Social Verification API 實現。

依照這些步驟，Logto Google 連接器會精確請求應用程式所需的權限，不多也不少。

提示:

若你的應用程式請求這些權限範圍以存取 Google API 並執行操作，請務必在 Logto Google 連接器啟用 持久 API 存取權杖儲存（Store tokens for persistent API access）。詳情請見下一節。

步驟 5：自訂驗證 (Authentication) 提示​

在 Logto 設定 Prompts 以控制使用者驗證 (Authentication) 體驗。Prompts 是一個字串陣列，指定所需的使用者互動類型：

  • none - 授權伺服器不顯示任何驗證 (Authentication) 或同意畫面。若使用者尚未驗證 (Authentication) 或未預先同意所請求的權限範圍，則會回傳錯誤。可用於檢查現有驗證 (Authentication) / 同意狀態。
  • consent - 授權伺服器會在回傳資訊給用戶端前提示使用者同意。啟用 Google API 離線存取（offline access） 時必須使用。
  • select_account - 授權伺服器會提示使用者選擇帳戶。適用於有多個 Google 帳戶的使用者選擇登入帳戶。

步驟 6：一般設定​

以下是一些不會阻礙 Google 連線，但可能影響終端使用者驗證 (Authentication) 體驗的通用設定。

同步個人檔案資訊​

在 Google 連接器中，你可以設定同步個人檔案資訊（如使用者名稱與頭像）的政策。可選擇：

  • 僅註冊時同步（Only sync at sign-up）：僅於使用者首次登入時取得個人資訊。
  • 每次登入時同步（Always sync at sign-in）：每次登入時都會更新個人資訊。

儲存權杖以存取 Google API（選填）​

若你希望存取 Google API 並在使用者授權下執行操作（無論是社交登入或帳號連結），Logto 需取得特定 API 權限範圍並儲存權杖。

  1. 在 Google Cloud Console 的 OAuth 同意畫面設定及 Logto Google 連接器中新增所需權限範圍。
  2. 在 Logto Google 連接器啟用 持久 API 存取權杖儲存（Store tokens for persistent API access）。Logto 會將 Google 存取權杖與重新整理權杖安全儲存於 Secret Vault。
  3. 為確保能取得重新整理權杖，請如下設定 Logto Google 連接器：
    • Prompts 包含 consent
    • 啟用 離線存取（Offline Access）
注意:

你不需要在 Logto 的 Scope 欄位加入 offline_access —— 這麼做可能會導致錯誤。Google 在啟用離線存取時會自動使用 access_type=offline。

步驟 7：啟用 Google One Tap（選填）​

Google One Tap 是一種安全且簡便的方式，讓使用者透過彈出式介面以 Google 帳戶登入你的网站。

當你完成 Google 連接器設定後，會在連接器詳情頁看到 Google One Tap 卡片。切換開關即可啟用 Google One Tap。

Google One Tap 設定選項​

  • 自動選擇憑證（Auto-select credential if possible） - 若 符合特定條件，自動以 Google 帳戶登入使用者
  • 使用者點擊 / 點觸外部時取消提示（Cancel the prompt if user clicks/taps outside） - 若使用者點擊或點觸提示框外部則關閉 Google One Tap 提示。若停用，使用者必須點擊關閉按鈕才能關閉提示。
  • 在 ITP 瀏覽器啟用升級版 One Tap UX（Enable Upgraded One Tap UX on ITP browsers） - 在啟用 Intelligent Tracking Prevention (ITP) 的瀏覽器上啟用升級版 Google One Tap 體驗。詳情請參閱 官方文件。
注意:

請務必將你的網域加入 OAuth 用戶端設定的 授權的 JavaScript 來源（Authorized JavaScript origins）。否則 Google One Tap 將無法顯示。

Google One Tap 的重要限制​

若你同時啟用 持久 API 存取權杖儲存（Store tokens for persistent API access） 與 Google One Tap，你不會自動取得存取權杖或所請求的權限範圍。

Google One Tap 登入（不同於標準「以 Google 登入」按鈕）不會發放 OAuth 存取權杖。它僅回傳一個 ID 權杖（簽署過的 JWT），可驗證使用者身分，但無法授予 API 存取權。

若需讓 Google One Tap 使用者存取 Google API，可在使用者以 Google One Tap 登入後，透過 Logto 的 Social Verification API 重新啟動聯邦社交授權流程。如此可按需請求額外權限範圍並更新使用者的權杖組，無需預先在 Logto Google 連接器填寫這些權限範圍。這種方式實現漸進式授權，僅在應用程式實際需要時才提示使用者額外權限。

詳情請參閱 Google One Tap 限制 官方文件。

步驟 8：測試並發佈你的應用程式​

內部應用程式​

若你的 Google 受眾（Audience） 類型設為 內部（Internal），應用程式僅對你組織內的 Google Workspace 使用者開放。你可用組織內任一帳戶進行測試。

外部應用程式​

若你的 受眾（Audience） 類型為 外部（External）：

  1. 開發期間：前往 OAuth 同意畫面 > 測試使用者（Test users），新增測試使用者電子郵件地址。僅這些使用者可登入你的應用程式。
  2. 正式上線：在 OAuth 同意畫面區段點擊 發佈應用程式（Publish App），讓所有 Google 帳戶使用者皆可存取。
備註:

具有敏感或受限權限範圍的應用程式，可能需經 Google 驗證後才能發佈。此流程可能需時數週。

使用 Google 連接器 (Connector)​

建立 Google 連接器 (Connector) 並與 Google 連結後，你可以將其整合進終端使用者流程。根據需求選擇合適的選項：

啟用「使用 Google 登入」​

  1. 在 Logto 控制台，前往 登入體驗 > 註冊與登入。
  2. 在 社交登入 區塊新增 Google 連接器 (Connector)，讓使用者可用 Google 驗證 (Authentication)。
  3. 可選擇在登入與註冊頁啟用 Google One Tap，提供更流暢的驗證 (Authentication) 體驗。

進一步了解 社交登入體驗。

使用 Account API 在你的應用程式中打造自訂帳號中心，讓已登入使用者連結或解除 Google 帳號。參考 Account API 教學

提示:

你可以僅啟用 Google 連接器 (Connector) 以供帳號連結與 API 存取，不必啟用社交登入。

存取 Google API 並執行操作​

你的應用程式可從 Secret Vault 取得儲存的 Google 存取權杖 (Access token)，呼叫 Google API 並自動化後端任務（例如：管理 Google 雲端硬碟檔案、建立行事曆事件、或透過 Gmail 寄送郵件）。請參考相關教學以取得 API 存取所需的權杖。

管理使用者的 Google 身分​

使用者連結 Google 帳號後，管理員可在 Logto 控制台管理該連結：

  1. 前往 Logto 控制台 > 使用者管理 並開啟該使用者的個人資料。
  2. 在 社交連結 區塊找到 Google 項目並點擊 管理。
  3. 在此頁面，管理員可管理使用者的 Google 連結、檢視所有從 Google 帳號授權並同步的個人資料資訊，以及檢查存取權杖 (Access token) 狀態。

參考資料​

Google 身分：設定 OAuth 2.0

Google 身分服務（One Tap）

 Google Cloud Console