設定 OpenID Connect (OIDC) 社交登入 (Set up social login with OpenID Connect (OIDC))
Logto 官方的 OpenID Connect (OIDC) 協議連接器。
本指南假設你已對 Logto 連接器 (Connectors) 有基本了解。若不熟悉，請參閱 連接器 (Connectors) 指南以開始使用。
開始使用 (Get started)
OIDC 連接器讓 Logto 能夠連接任何支援 OIDC 協議的社交身分提供者。使用 OIDC 連接器，你的應用程式可以：
- 新增社交登入按鈕
- 將使用者帳號與社交身分連結
- 從社交提供者同步使用者個人資料資訊
- 透過 Logto Secret Vault 安全儲存權杖，存取第三方 API 以自動化任務（例如：編輯 Google Docs、管理應用程式中的 Calendar 事件）
要設定這些驗證 (Authentication) 功能，請先在 Logto 中建立 OIDC 連接器：
- 前往 Logto 控制台 > 連接器 > 社交連接器。
- 點擊 新增社交連接器，選擇 OIDC，點擊 下一步，並依照分步教學完成整合。
OIDC 連接器是 Logto 中一種特殊的連接器，你可以新增多個基於 OIDC 協議的連接器。
建立你的 OIDC 應用程式
當你開啟本頁時，我們相信你已經知道要連接哪個社交身分提供者。首先，請確認該身分提供者支援 OIDC 協議，這是設定有效連接器的前提。然後，依照身分提供者的指引註冊並建立 OIDC 授權所需的應用程式。
設定你的連接器 (Connector)
基於安全考量，我們僅支援「授權碼 (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 探索端點中的 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 授權伺服器的 URL 相符，且必須是 RP 信任的 URI。RP 收到 JWT 時，會檢查 iss 宣告，確保該權杖由信任的 IdP 簽發，且僅用於 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 flows，但 Logto 連接器只支援授權碼流程？經過評估，implicit 與 hybrid flows 的安全性低於授權碼流程。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 tokens) 安全儲存在 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 tokens)，以呼叫身分提供者 API 並自動化後端任務。具體能力取決於你的身分提供者與你所申請的權限範圍 (Scopes)。請參閱 API 存取權杖取得指南。
管理使用者的社交身分
使用者綁定社交帳號後，管理員可在 Logto Console 管理該連線：
- 前往 Logto console > 使用者管理 並開啟該使用者的個人資料頁。
- 在 社交連線 區塊找到身分提供者項目並點擊 管理。
- 在此頁面，管理員可管理使用者的社交連線、檢視所有從社交帳號授權並同步的個人資料資訊，以及檢查存取權杖 (Access token) 狀態。
部分身分提供者的存取權杖 (Access token) 回應不包含具體權限範圍 (Scopes) 資訊，因此 Logto 無法直接顯示使用者授權的權限列表。但只要使用者在授權時同意所請求的權限範圍，你的應用程式在存取 OIDC API 時就會擁有相應權限。