設定 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 連接器：
- 前往 Logto 控制台 > 連接器 > 社交連接器。
- 點擊 新增社交連接器，選擇 OAuth 2.0，點擊 下一步，並依照分步教學完成整合。
OAuth 連接器是 Logto 中一種特殊的連接器，你可以新增多個基於 OAuth 協議的連接器。
建立你的 OAuth 應用程式
當你開啟本頁時，我們相信你已經知道要連接哪個社交身分提供者。首先，請確認該身分提供者支援 OAuth 協議，這是設定有效連接器的前提。然後，依照身分提供者的指引註冊並建立用於 OAuth 授權的相關應用程式。
設定你的連接器 (Connector)
基於安全考量，我們僅支援「授權碼 (Authorization Code)」授權類型，這也能完美符合 Logto 的使用情境。
clientId 和 clientSecret 可以在你的 OAuth 應用程式詳細資訊頁面找到。
clientId：client ID 是在向授權伺服器註冊時用來識別用戶端應用程式的唯一識別碼。授權伺服器會利用這個 ID 來驗證用戶端應用程式的身分，並將任何授權的存取權杖 (Access token) 與該特定用戶端應用程式關聯。
clientSecret：client secret 是授權伺服器在註冊時發給用戶端應用程式的機密金鑰。用戶端應用程式在請求存取權杖 (Access token) 時，會使用這個金鑰向授權伺服器驗證自身身分。client secret 屬於機密資訊，必須隨時妥善保管。
tokenEndpointAuthMethod：權杖端點驗證方法是用戶端應用程式在請求存取權杖 (Access token) 時，向授權伺服器驗證自身身分所用的方法。請參考 OAuth 2.0 服務提供者的 OpenID Connect 探索端點中的 token_endpoint_auth_methods_supported 欄位，或查閱相關文件以瞭解支援的方法。
clientSecretJwtSigningAlgorithm (選填)：僅當 tokenEndpointAuthMethod 為 client_secret_jwt 時需要。client secret JWT 簽章演算法用於用戶端應用程式在權杖請求 (Token request) 時簽署傳送給授權伺服器的 JWT。
scope：scope 參數用於指定用戶端應用程式請求存取的資源與權限範圍 (Scopes)。scope 通常是一串以空格分隔的值，代表特定權限。例如，scope 設為 "read write" 可能表示用戶端應用程式請求讀取與寫入使用者資料的權限。
你應該能在社交服務商的文件中找到 authorizationEndpoint、tokenEndpoint 和 userInfoEndpoint。
authenticationEndpoint：此端點用於啟動驗證流程。驗證流程通常包含使用者登入並授權用戶端應用程式存取其資源。
tokenEndpoint：此端點供用戶端應用程式取得可用於存取所請求資源的存取權杖 (Access token)。用戶端應用程式通常會帶著授權碼 (Authorization code) 與授權類型 (Grant type) 請求權杖。
userInfoEndpoint：此端點供用戶端應用程式取得使用者的額外資訊，例如全名、電子郵件或大頭貼。通常在取得存取權杖 (Access token) 後存取 user info 端點。
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。
設定類型 (Config types)
| 名稱 | 類型 | 必填 |
|---|---|---|
| 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 |
| string | false | ||
| phone | string | false | phone |
一般設定
以下是一些不會阻礙你連接身分提供者，但可能影響終端使用者驗證體驗的通用設定。
社交按鈕名稱與 Logo
如果你想在登入頁顯示社交按鈕，可以設定社交身分提供者的名稱與Logo（深色模式與淺色模式）。這有助於使用者辨識社交登入選項。
身分提供者名稱
每個社交連接器都有唯一的身分提供者 (IdP, Identity Provider) 名稱，用於區分使用者身分。常見連接器會使用固定 IdP 名稱，自訂連接器則需填入唯一值。詳情請參閱 IdP 名稱說明。
同步個人資料資訊
在 OAuth 連接器中，你可以設定同步個人資料（如使用者名稱與大頭貼）的政策。可選擇：
- 僅於註冊時同步：使用者首次登入時取得一次個人資料。
- 每次登入時皆同步：每次登入時都會更新個人資料。
儲存權杖以存取第三方 API（選填）
如果你想存取身分提供者的 API 並以使用者授權執行操作（無論是社交登入或帳號連結），Logto 需要取得特定 API 權限範圍 (Scopes) 並儲存權杖。
- 依上述說明在 scope 欄位加入所需權限範圍
- 在 Logto OAuth 連接器中啟用 持久 API 存取權杖儲存。Logto 會將存取權杖 (Access token) 安全儲存在 Secret Vault。
- 對於標準 OAuth/OIDC 身分提供者，必須包含
offline_access權限範圍以取得重新整理權杖 (Refresh token)，避免重複要求使用者同意。
請妥善保管你的 client secret，切勿在前端程式碼中暴露。如果發現外洩，請立即在身分提供者的應用程式設定中產生新金鑰。
使用 OAuth 連接器
建立 OAuth 連接器並連接到你的身分提供者後，你可以將其整合到終端使用者流程中。請依需求選擇下列方式：
啟用社交登入按鈕
- 在 Logto Console 前往 登入體驗 > 註冊與登入。
- 在 社交登入 區段新增 OAuth 連接器，讓使用者可透過你的身分提供者驗證。
進一步瞭解 社交登入體驗。
連結或解除連結社交帳號
使用 Account API 在你的應用程式中建立自訂帳號中心，讓已登入使用者連結或解除連結社交帳號。參考 Account API 教學
你可以僅啟用 OAuth 連接器作為帳號連結與 API 存取用途，而不必啟用社交登入。
存取身分提供者 API 並執行操作
你的應用程式可從 Secret Vault 取得已儲存的存取權杖 (Access token)，以呼叫身分提供者 API 並自動化後端任務。具體能力取決於你的身分提供者及你申請的權限範圍 (Scopes)。請參閱相關指南以瞭解如何取得儲存的權杖進行 API 存取。
管理使用者的社交身分
使用者連結社交帳號後，管理員可在 Logto Console 管理該連線：
- 前往 Logto console > 使用者管理 並開啟該使用者的個人資料頁。
- 在 社交連線 區塊找到身分提供者項目並點擊 管理。
- 在此頁面，管理員可管理使用者的社交連線、檢視所有從社交帳號授權並同步的個人資料資訊，以及檢查存取權杖 (Access token) 狀態。
部分身分提供者回傳的存取權杖 (Access token) 回應不包含具體權限範圍 (Scopes) 資訊，因此 Logto 無法直接顯示使用者授權的權限清單。不過，只要使用者在授權時同意了所請求的權限範圍，你的應用程式在存取 OAuth API 時就會擁有相應權限。
參考資料
OAuth 2.0 授權框架 (The OAuth 2.0 Authorization Framework)