設定 OAuth 2.0 協議社交登入 (Set up social login with OAuth 2.0 protocol)

官方 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 是在向簽發者（Issuer）註冊時，用來識別用戶端應用程式的唯一識別碼。簽發者（Issuer）會利用這個 ID 來驗證用戶端應用程式的身分，並將任何授權的存取權杖（Access token）與該應用程式關聯。

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

tokenEndpointAuthMethod：權杖端點驗證方法（token endpoint authentication method）是用戶端應用程式在請求存取權杖（Access token）時，向簽發者（Issuer）驗證自身身分所用的方法。要查詢支援的方法，請參考 OAuth 2.0 服務提供者的 OpenID Connect discovery endpoint 中的 token_endpoint_auth_methods_supported 欄位，或查閱相關文件。

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

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

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

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

tokenEndpoint：此端點供用戶端應用程式取得存取權杖（Access token），以便存取所請求的資源。用戶端應用程式通常會帶著授權碼（Authorization code）和授權類型（Grant type）向此端點請求存取權杖（Access token）。

userInfoEndpoint：此端點供用戶端應用程式取得使用者的額外資訊，例如全名、電子郵件或大頭貼。通常在取得存取權杖（Access token）後存取此端點。

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

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

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

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

備註:

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

設定類型

名稱	類型	必填
authorizationEndpoint	string	true
userInfoEndpoint	string	true
clientId	string	true
clientSecret	string	true
tokenEndpointResponseType	enum	false
responseType	string	false
grantType	string	false
tokenEndpoint	string	false
scope	string	false
customConfig	Record<string, string>	false
profileMap	ProfileMap	false

ProfileMap 欄位	類型	必填	預設值
id	string	false	id
name	string	false	name
avatar	string	false	avatar
email	string	false	email
phone	string	false	phone

一般設定

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

社交按鈕名稱與 Logo

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

身分提供者名稱

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

同步個人資料資訊

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

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

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

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

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

注意:

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

使用 OAuth 連接器

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

啟用社交登入按鈕

1. 在 Logto Console 前往 登入與帳號 > 註冊與登入。
2. 在 社交登入 區段新增 OAuth 連接器，讓使用者能以你的身分提供者驗證（Authentication）。

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

連結或解除連結社交帳號

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

提示:

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

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

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

管理使用者的社交身分

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

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

備註:

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

參考資料

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