設定 OpenID Connect (OIDC) 社交登入 (Set up social login with OpenID Connect (OIDC))
官方 Logto OpenID Connect (OIDC) 協議連接器。
本指南假設你已對 Logto 連接器 (Connectors) 有基本了解。若不熟悉，請參閱 連接器 (Connectors) 指南以開始使用。
開始使用
OIDC 連接器讓 Logto 能連接任何支援 OIDC 協議的社交身分提供者。使用 OIDC 連接器，你的應用程式可以：
- 新增社交登入按鈕
- 將使用者帳號與社交身分連結
- 從社交提供者同步使用者個人資料資訊
- 透過 Logto Secret Vault 安全儲存權杖，存取第三方 API 以自動化任務（例如：編輯 Google 文件、管理應用程式中的行事曆事件）
要設定這些驗證 (Authentication) 功能，請先在 Logto 建立 OIDC 連接器：
- 前往 Logto 控制台 > 連接器 > 社交連接器。
- 點擊 新增社交連接器，選擇 OIDC，點擊 下一步，並依照分步教學完成整合。
OIDC 連接器是 Logto 中一種特殊的連接器，你可以新增多個基於 OIDC 協議的連接器。
建立你的 OIDC 應用程式
當你看到這個頁面時，我們相信你已經知道要連接哪個社交身分提供者。首先，請確認該身分提供者支援 OIDC 協議，這是設定有效連接器的前提。然後，依照身分提供者的指引註冊並建立 OIDC 授權所需的相關應用程式。
設定你的連接器
基於安全考量，我們僅支援「授權碼（Authorization Code）」授權類型，這也完全符合 Logto 的使用情境。
clientId 和 clientSecret 可以在你的 OIDC 應用程式詳細頁面找到。
clientId：client ID 是用於在註冊時識別用戶端應用程式的唯一識別碼。授權伺服器會用這個 ID 來驗證用戶端應用程式的身分，並將任何授權的存取權杖（Access token）與該特定用戶端應用程式關聯。
clientSecret：client secret 是授權伺服器在註冊時發給用戶端應用程式的機密金鑰。用戶端應用程式在請求存取權杖（Access token）時，會用這個金鑰向授權伺服器驗證自身身分。client secret 屬於機密資訊，必須隨時妥善保管。
tokenEndpointAuthMethod：權杖端點驗證方法（token endpoint authentication method）是用戶端應用程式在請求存取權杖（Access token）時，向授權伺服器驗證自身身分所用的方法。請參考 OAuth 2.0 服務提供者的 OpenID Connect 探索端點（discovery endpoint）中的 token_endpoint_auth_methods_supported 欄位，或查閱相關文件以瞭解支援的方法。
clientSecretJwtSigningAlgorithm（選填）：僅當 tokenEndpointAuthMethod 為 client_secret_jwt 時需要。client secret JWT 簽章演算法用於用戶端應用程式在權杖請求（Token request）時簽署傳送給授權伺服器的 JWT。
scope：scope 參數用於指定用戶端應用程式請求存取的資源與權限範圍（Scopes）。scope 通常是一串以空格分隔的值，代表特定權限。例如，scope 設為 "read write" 可能表示用戶端應用程式請求讀寫使用者資料的權限。
你應該能在 OpenID Provider 的設定資訊中找到 authorizationEndpoint、tokenEndpoint、jwksUri 和 issuer。這些資訊通常可在社交平台的文件中查到。
authenticationEndpoint：這個端點用於啟動驗證流程。驗證流程通常包含使用者登入並授權用戶端應用程式存取其資源。
tokenEndpoint：這個端點讓用戶端應用程式取得 ID 權杖（ID token），以便存取所請求的資源。用戶端應用程式通常會帶著授權碼（authorization code）和授權類型（grant type）向 token endpoint 發送請求，以取得 ID 權杖。
jwksUri：這是社交身分提供者（IdP, Identity provider）的 JSON Web Key Set（JWKS）網址端點。JWKS 是一組加密金鑰，IdP 用來簽署與驗證驗證流程中發出的 JSON Web Token（JWT）。jwksUri 讓信賴方（RP, Relying Party）取得 IdP 用來簽署 JWT 的公開金鑰，以驗證從 IdP 收到的 JWT 的真實性與完整性。
issuer：這是 IdP 的唯一識別碼，RP 會用來驗證從 IdP 收到的 JWT。它會以 iss 宣告 (Claim) 包含在 JWT 中（ID 權杖永遠是 JWT）。issuer 的值應與 IdP 授權伺服器的 URL 相符，且必須是 RP 信任的 URI。RP 收到 JWT 時，會檢查 iss 宣告，確保它是由信任的 IdP 簽發，且該 JWT 是給 RP 使用的。
jwksUri 和 issuer 結合起來，為 RP 在驗證流程中驗證終端使用者身分提供安全機制。RP 透過 jwksUri 取得公開金鑰，驗證 IdP 發出的 JWT 的真實性與完整性；issuer 則確保 RP 只接受由信任的 IdP 簽發、且專為 RP 使用的 JWT。
由於每次都需要驗證請求（Authentication request），我們提供 authRequestOptionalConfig 來包裝所有選填設定，詳細內容請參考 OIDC 驗證請求 (Authentication Request)。你可能會發現這裡沒有 nonce，因為 nonce 每次請求都要唯一，我們將其產生邏輯放在程式碼實作中，所以不用擔心！前述的 jwksUri 和 issuer 也包含在 idTokenVerificationConfig 中。
你可能會好奇，為什麼標準 OIDC 協議支援 implicit 與 hybrid 流程，但 Logto 連接器只支援授權流程（Authorization flow）。這是因為 implicit 與 hybrid 流程的安全性較低。Logto 著重安全性，因此僅支援授權流程，為用戶提供最高安全等級，雖然便利性略低。
responseType 和 grantType 在「授權碼（Authorization Code）」流程下只能是固定值，因此我們將其設為選填，預設值會自動填入。
針對所有流程類型，我們提供選填的 customConfig 欄位讓你放自訂參數。
每個社交身分提供者對 OIDC 標準協議可能有自己的變體。如果你的目標身分提供者嚴格遵循 OIDC 標準協議，則不需要特別處理 customConfig。
設定類型
| 名稱 | 類型 | 必填 |
|---|---|---|
| scope | string | 是 |
| clientId | string | 是 |
| clientSecret | string | 是 |
| authorizationEndpoint | string | 是 |
| tokenEndpoint | string | 是 |
| idTokenVerificationConfig | IdTokenVerificationConfig | 是 |
| authRequestOptionalConfig | AuthRequestOptionalConfig | 否 |
| customConfig | Record<string, string> | 否 |
| AuthRequestOptionalConfig 屬性 | 類型 | 必填 |
|---|---|---|
| responseType | string | 否 |
| tokenEndpoint | string | 否 |
| responseMode | string | 否 |
| display | string | 否 |
| prompt | string | 否 |
| maxAge | string | 否 |
| uiLocales | string | 否 |
| idTokenHint | string | 否 |
| loginHint | string | 否 |
| acrValues | string | 否 |
| IdTokenVerificationConfig 屬性 | 類型 | 必填 |
|---|---|---|
| jwksUri | string | 是 |
| issuer | string | string[] | 否 |
| audience | string | string[] | 否 |
| algorithms | string[] | 否 |
| clockTolerance | string | number | 否 |
| crit | Record<string, string | boolean> | 否 |
| currentDate | Date | 否 |
| maxTokenAge | string | number | 否 |
| subject | string | 否 |
| typ | string | 否 |
更多 IdTokenVerificationConfig 詳細說明請參考 這裡。
一般設定
以下是一些不會阻礙你連接身分提供者，但可能影響終端使用者驗證體驗的一般設定。
社交按鈕名稱與 Logo
如果你希望在登入頁面顯示社交按鈕，可以設定社交身分提供者的名稱與Logo（深色模式與淺色模式）。這有助於使用者辨識社交登入選項。
身分提供者名稱
每個社交連接器都有唯一的身分提供者（IdP, Identity Provider）名稱，用來區分使用者身分。常見連接器會使用固定的 IdP 名稱，自訂連接器則需填入唯一值。詳情請參閱 IdP 名稱說明。
同步個人資料資訊
在 OIDC 連接器中，你可以設定同步個人資料（如使用者名稱與頭像）的政策。可選擇：
- 僅註冊時同步：使用者首次登入時會取得一次個人資料。
- 每次登入時皆同步：每次使用者登入時都會更新個人資料。
儲存權杖以存取第三方 API（選填）
如果你希望存取身分提供者的 API 並以使用者授權執行操作（無論是社交登入或帳號綁定），Logto 需要取得特定 API 權限範圍（Scopes）並儲存權杖（Tokens）。
- 依上述說明在 scope 欄位加入所需權限範圍
- 在 Logto OIDC 連接器中啟用 持久化 API 存取權杖儲存。Logto 會將存取權杖（Access token）安全地儲存在 Secret Vault。
- 對於標準 OAuth/OIDC 身分提供者，必須包含
offline_access權限範圍以取得重新整理權杖（Refresh token），避免重複要求使用者同意。
請妥善保管你的 client secret，切勿在前端程式碼中暴露。如果發現外洩，請立即在身分提供者的應用程式設定中產生新金鑰。
使用 OIDC 連接器
當你建立好 OIDC 連接器並連接到身分提供者後，即可將其整合進終端使用者流程。請依需求選擇下列方式：
啟用社交登入按鈕
- 在 Logto Console 前往 登入體驗 > 註冊與登入。
- 在 社交登入 區塊新增 OIDC 連接器，讓使用者能以你的身分提供者驗證。
進一步瞭解 社交登入體驗。
綁定或解除綁定社交帳號
使用 Account API 在你的應用程式中建立自訂帳號中心，讓已登入使用者綁定或解除綁定社交帳號。參考 Account API 教學
你可以只啟用 OIDC 連接器作為帳號綁定與 API 存取用途，而不啟用社交登入。
存取身分提供者 API 並執行操作
你的應用程式可以從 Secret Vault 取得儲存的存取權杖（Access token），呼叫身分提供者 API 並自動化後端任務。具體能力取決於你的身分提供者與你申請的權限範圍。請參考相關教學以瞭解如何取得儲存的權杖進行 API 存取。
管理使用者的社交身分
當使用者綁定社交帳號後，管理員可在 Logto Console 管理該連線：
- 前往 Logto console > 使用者管理 並開啟該使用者的個人資料。
- 在 社交連線 區塊找到身分提供者項目並點擊 管理。
- 在此頁面，管理員可管理使用者的社交連線、檢視所有從社交帳號授權並同步的個人資料資訊，以及檢查存取權杖狀態。
部分身分提供者的存取權杖（Access token）回應不包含具體權限範圍（Scopes）資訊，因此 Logto 無法直接顯示使用者授權的權限清單。不過，只要使用者在授權時同意了所請求的權限範圍，你的應用程式在存取 OIDC API 時就會擁有相應權限。