跳至主要內容

設定 OAuth 2.0 協議社交登入

官方 Logto OAuth 2.0 協議連接器。

提示:

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

開始使用​

OAuth 連接器讓 Logto 能連接任意支援 OAuth 2.0 協議的社交身分提供者。使用 OAuth 連接器，你的應用程式可以：

  • 新增社交登入按鈕
  • 將使用者帳號與社交身分連結
  • 從社交提供者同步使用者個人資料資訊
  • 透過 Logto Secret Vault 安全儲存權杖，存取第三方 API 以自動化任務（例如：編輯 Google 文件、管理應用程式中的行事曆事件）

要設定這些驗證 (Authentication) 功能，請先在 Logto 建立一個 OAuth 2.0 連接器：

  1. 前往 Logto 控制台 > 連接器 > 社交連接器。
  2. 點擊 新增社交連接器，選擇 OAuth 2.0，點擊 下一步，並依照分步教學完成整合。
備註:

OAuth 連接器是 Logto 中一種特殊的連接器，你可以新增多個基於 OAuth 協議的連接器。

建立你的 OAuth 應用程式​

當你開啟本頁時，我們相信你已經知道要連接哪個社交身分提供者。首先，請確認該身分提供者支援 OAuth 協議，這是設定有效連接器的前提。然後，依照身分提供者的指引註冊並建立用於 OAuth 授權的相關應用程式。

設定你的連接器​

出於安全考量，我們僅支援「授權碼（Authorization Code）」授權類型，這也能完美符合 Logto 的情境。

clientId 和 clientSecret 可在你的 OAuth 應用程式詳細頁面找到。

clientId：client ID 是在向授權伺服器註冊時用來識別用戶端應用程式的唯一識別碼。授權伺服器會用這個 ID 來驗證用戶端應用程式的身分，並將任何授權的存取權杖（Access token）與該應用程式關聯。

clientSecret：client secret 是授權伺服器在註冊時發給用戶端應用程式的機密金鑰。用戶端應用程式在請求存取權杖時會用這個金鑰向授權伺服器驗證自身身分。client secret 屬於機密資訊，必須隨時妥善保管。

tokenEndpointAuthMethod：權杖端點驗證方法是用戶端應用程式在請求存取權杖時用來向授權伺服器驗證自身身分的方法。要查詢支援的方法，請參考 OAuth 2.0 服務提供者的 OpenID Connect discovery 端點中的 token_endpoint_auth_methods_supported 欄位，或查閱相關文件。

clientSecretJwtSigningAlgorithm（選填）：僅當 tokenEndpointAuthMethod 為 client_secret_jwt 時需要。client secret JWT 簽章演算法用於用戶端應用程式在權杖請求時簽署發送給授權伺服器的 JWT。

scope：scope 參數用於指定用戶端應用程式請求存取的資源與權限範圍（Scopes）。scope 通常是一個以空格分隔的權限清單。例如，scope 設為 "read write" 代表應用程式請求讀寫使用者資料的權限。

你應該能在社交服務商的文件中找到 authorizationEndpoint、tokenEndpoint 和 userInfoEndpoint。

authenticationEndpoint：此端點用於啟動驗證流程。驗證流程通常包含使用者登入並授權用戶端應用程式存取其資源。

tokenEndpoint：此端點用於用戶端應用程式取得可用於存取所請求資源的存取權杖（Access token）。用戶端應用程式通常會帶著授權碼與授權類型向此端點發送請求以取得存取權杖。

userInfoEndpoint：此端點用於用戶端應用程式取得關於使用者的額外資訊，例如全名、電子郵件或頭像。通常在取得存取權杖後才會存取 user info 端點。

Logto 也提供 profileMap 欄位，讓你自訂社交服務商回傳的使用者資料欄位對應（通常非標準）。key 為 Logto 標準使用者資料欄位名稱，value 則為社交服務商的欄位名稱。目前 Logto 只關注社交資料中的 'id'、'name'、'avatar'、'email' 和 'phone'，其中僅 'id' 為必填，其餘為選填。

responseType 和 grantType 僅能為授權碼授權類型的固定值，因此我們將其設為選填，預設值會自動填入。

舉例來說，你可以參考 Google 使用者資料回應，其 profileMap 應如下：

{
  "id": "sub",
  "avatar": "picture"
}
備註:

我們提供了選填的 customConfig 欄位，讓你放自訂參數。 每個社交身分提供者在 OAuth 標準協議上可能有自己的變體。如果你的目標身分提供者完全遵循 OAuth 標準協議，則無需理會 customConfig。

設定類型​

名稱類型必填
authorizationEndpointstringtrue
userInfoEndpointstringtrue
clientIdstringtrue
clientSecretstringtrue
tokenEndpointResponseTypeenumfalse
responseTypestringfalse
grantTypestringfalse
tokenEndpointstringfalse
scopestringfalse
customConfigRecord<string, string>false
profileMapProfileMapfalse
ProfileMap 欄位類型必填預設值
idstringfalseid
namestringfalsename
avatarstringfalseavatar
emailstringfalseemail
phonestringfalsephone

一般設定​

以下是一些不會阻礙你連接身分提供者，但可能影響終端使用者驗證體驗的通用設定。

如果你想在登入頁顯示社交登入按鈕，可以設定社交身分提供者的名稱與Logo（深色模式與淺色模式）。這有助於使用者辨識社交登入選項。

身分提供者名稱​

每個社交連接器都有唯一的身分提供者（IdP, Identity Provider）名稱，用於區分使用者身分。常見連接器會使用固定 IdP 名稱，自訂連接器則需填入唯一值。詳情請參閱 IdP 名稱說明。

同步個人資料資訊​

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

  • 僅在註冊時同步：僅於使用者首次登入時取得個人資料。
  • 每次登入時皆同步：每次使用者登入時都會更新個人資料。

儲存權杖以存取第三方 API（選填）​

若你想存取身分提供者的 API 並以使用者授權執行操作（無論是社交登入或帳號連結），Logto 需取得特定 API 權限範圍（Scopes）並儲存權杖。

  1. 依上述說明，在 scope 欄位加入所需權限範圍
  2. 在 Logto OAuth 連接器中啟用 儲存權杖以持久存取 API。Logto 會將存取權杖安全儲存在 Secret Vault。
  3. 對於標準 OAuth/OIDC 身分提供者，必須包含 offline_access 權限範圍以取得重新整理權杖（Refresh token），避免重複要求使用者同意。
注意:

請妥善保管你的 client secret，切勿在前端程式碼中暴露。如有洩漏，請立即在身分提供者的應用程式設定中產生新金鑰。

使用 OAuth 連接器​

當你建立好 OAuth 連接器並連結到身分提供者後，即可將其整合進終端使用者流程。請依需求選擇下列方式：

啟用社交登入按鈕​

  1. 在 Logto Console，前往 登入體驗 > 註冊與登入。
  2. 在 社交登入 區段新增 OAuth 連接器，讓使用者可透過你的身分提供者驗證。

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

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

提示:

你可以僅啟用 OAuth 連接器作為帳號連結與 API 存取用途，而不啟用社交登入。

存取身分提供者 API 並執行操作​

你的應用程式可從 Secret Vault 取得儲存的存取權杖，呼叫身分提供者 API 並自動化後端任務。具體能力取決於身分提供者與你申請的權限範圍。請參閱相關指南以取得 API 存取所需的權杖。

管理使用者的社交身分​

當使用者連結社交帳號後，管理員可在 Logto Console 管理該連線：

  1. 前往 Logto console > 使用者管理 並開啟該使用者的個人資料。
  2. 在 社交連線 區塊找到身分提供者項目並點擊 管理。
  3. 在此頁面，管理員可管理使用者的社交連線、檢視所有從社交帳號授權並同步的個人資料資訊，以及檢查存取權杖狀態。
備註:

部分身分提供者的存取權杖回應不包含具體權限範圍（Scopes）資訊，因此 Logto 無法直接顯示使用者授權的權限清單。但只要使用者在授權時同意了所請求的權限範圍，你的應用程式在存取 OAuth API 時就會擁有相應權限。

參考資料​

OAuth 2.0 授權框架 (The OAuth 2.0 Authorization Framework)