設定 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：權杖端點驗證方法是用戶端應用程式在請求存取權杖 (Access token) 時，向授權伺服器驗證自身身分所用的方法。請參閱 OAuth 2.0 服務提供者的 OpenID Connect 探索端點中的 token_endpoint_auth_methods_supported 欄位，或查閱相關文件以瞭解支援的方法。
clientSecretJwtSigningAlgorithm（選填）：僅當 tokenEndpointAuthMethod 為 client_secret_jwt 時需要。client secret JWT 簽章演算法用於用戶端應用程式在權杖請求時簽署發送給授權伺服器的 JWT。
scope：scope 參數用於指定用戶端應用程式請求存取的資源與權限範圍 (Scopes)。scope 通常是一個以空格分隔的值清單，代表特定權限。例如，scope 設為 "read write" 可能表示用戶端應用程式請求對使用者資料的讀寫權限。
你應該能在 OpenID Provider 的設定資訊中找到 authorizationEndpoint、tokenEndpoint、jwksUri 和 issuer。這些資訊通常可在社交平台的文件中查到。
authenticationEndpoint：此端點用於啟動驗證流程。驗證流程通常包含使用者登入並授權用戶端應用程式存取其資源。
tokenEndpoint：此端點由用戶端應用程式用來取得可用於存取請求資源的 id 權杖 (ID token)。用戶端應用程式通常會帶著授權碼與授權類型向 token 端點發送請求以取得 id 權杖。
jwksUri：這是社交身分提供者（簡稱 IdP）的 JSON Web Key Set (JWKS) 取得網址。JWKS 是一組加密金鑰，IdP 用來簽署與驗證驗證流程中發出的 JSON Web Token (JWT)。jwksUri 讓信賴方（RP）取得 IdP 用來簽署 JWT 的公開金鑰，以驗證從 IdP 收到的 JWT 的真實性與完整性。
issuer：這是 IdP 的唯一識別碼，RP 會用來驗證從 IdP 收到的 JWT。它會以 iss 宣告 (Claim) 出現在 JWT 中（ID 權杖 (ID token) 一定是 JWT）。issuer 值應與 IdP 授權伺服器的網址一致，且必須是 RP 信任的 URI。RP 收到 JWT 時，會檢查 iss 宣告，確保該權杖是由信任的 IdP 發出，且僅用於 RP。
jwksUri 與 issuer 結合，為 RP 在驗證流程中提供安全機制來驗證終端使用者身分。RP 透過 jwksUri 取得公開金鑰，驗證 IdP 發出的 JWT 的真實性與完整性。issuer 值則確保 RP 只接受由信任的 IdP 發出的 JWT，且僅用於 RP。
由於每次都需要驗證請求，因此我們提供 authRequestOptionalConfig 來包裝所有選填設定。詳細內容可參閱 OIDC 驗證請求 (Authentication Request)。你可能會發現這裡沒有 nonce，因為 nonce 每次請求都應該不同，我們將其產生邏輯放在程式碼實作中，所以不用擔心！前述的 jwksUri 與 issuer 也包含在 idTokenVerificationConfig 內。
你可能會好奇，為什麼標準 OIDC 協議支援 implicit 與 hybrid 流程，但 Logto 連接器只支援授權流程。經過評估，implicit 與 hybrid 流程的安全性低於授權流程。Logto 著重安全性，因此僅支援授權流程，以確保用戶最高安全等級，即使這樣稍微不便。
responseType 與 grantType 在「授權碼（Authorization Code）」流程下只能是固定值，因此我們將其設為選填，預設值會自動填入。
對於所有流程類型，我們提供選填的 customConfig 欄位讓你放自訂參數。
每個社交身分提供者對 OIDC 標準協議可能有自己的變體。如果你的目標身分提供者完全遵循 OIDC 標準協議，則不需理會 customConfig。
設定類型
| 名稱 | 類型 | 必填 |
|---|---|---|
| scope | string | True |
| clientId | string | True |
| clientSecret | string | True |
| authorizationEndpoint | string | True |
| tokenEndpoint | string | True |
| idTokenVerificationConfig | IdTokenVerificationConfig | True |
| authRequestOptionalConfig | AuthRequestOptionalConfig | False |
| customConfig | Record<string, string> | False |
| AuthRequestOptionalConfig 屬性 | 類型 | 必填 |
|---|---|---|
| responseType | string | False |
| tokenEndpoint | string | False |
| responseMode | string | False |
| display | string | False |
| prompt | string | False |
| maxAge | string | False |
| uiLocales | string | False |
| idTokenHint | string | False |
| loginHint | string | False |
| acrValues | string | False |
| IdTokenVerificationConfig 屬性 | 類型 | 必填 |
|---|---|---|
| jwksUri | string | True |
| issuer | string | string[] | False |
| audience | string | string[] | False |
| algorithms | string[] | False |
| clockTolerance | string | number | False |
| crit | Record<string, string | boolean> | False |
| currentDate | Date | False |
| maxTokenAge | string | number | False |
| subject | string | False |
| typ | string | False |
更多 IdTokenVerificationConfig 詳細說明請參閱 這裡。
一般設定
以下是一些不會阻礙你連接身分提供者，但可能影響終端使用者驗證體驗的一般設定。
社交按鈕名稱與 Logo
如果你想在登入頁顯示社交按鈕，可以設定社交身分提供者的名稱與Logo（深色模式與淺色模式）。這有助於使用者辨識社交登入選項。
身分提供者名稱
每個社交連接器都有唯一的身分提供者（IdP）名稱，用來區分使用者身分。常見連接器會使用固定的 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 並自動化後端任務。具體能力取決於你的身分提供者及你申請的權限範圍 (Scopes)。請參閱相關指南以瞭解如何取得儲存的權杖以存取 API。
管理使用者的社交身分
當使用者連結社交帳號後，管理員可在 Logto Console 管理該連線：
- 前往 Logto console > 使用者管理 並開啟該使用者的個人檔案。
- 在 社交連線 區塊找到身分提供者項目並點擊 管理。
- 在此頁面，管理員可管理使用者的社交連線、檢視所有從社交帳號授權並同步的個人資訊，以及檢查存取權杖狀態。
部分身分提供者的 access token 回應不包含具體權限範圍 (Scope) 資訊，因此 Logto 無法直接顯示使用者授權的權限清單。不過，只要使用者在授權時同意了所請求的權限範圍，你的應用程式在存取 OIDC API 時就會擁有相應權限。