设置 OpenID Connect (OIDC) 社交登录
Logto 官方的 OpenID Connect (OIDC) 协议连接器。
本指南假设你对 Logto 连接器 (Connectors) 有基本的了解。对于不熟悉的人，请参考 连接器 (Connectors) 指南以开始了解。
入门
OIDC 连接器让 Logto 能够连接到任意支持 OIDC 协议的社交身份提供商 (IdP)。使用 OIDC 连接器，你的应用可以：
- 添加社交登录按钮
- 将用户账户与社交身份关联
- 从社交提供商同步用户资料信息
- 通过 Logto Secret Vault 的安全令牌存储访问第三方 API，实现自动化任务（例如编辑 Google Docs、在你的应用中管理日历事件）
要设置这些认证 (Authentication) 功能，首先需要在 Logto 中创建一个 OIDC 连接器：
- 前往 Logto 控制台 > 连接器 > 社交连接器。
- 点击 添加社交连接器，选择 OIDC，点击 下一步，并按照分步教程完成集成。
OIDC 连接器是 Logto 中一种特殊类型的连接器，你可以添加多个基于 OIDC 协议的连接器。
创建你的 OIDC 应用
当你打开此页面时，我们认为你已经知道要连接哪个社交身份提供商。首先需要确认该身份提供商支持 OIDC 协议，这是配置有效连接器的前提。然后，按照身份提供商的指引注册并创建用于 OIDC 授权 (Authorization) 的相关应用。
配置你的连接器
出于安全考虑，我们仅支持“授权码 (Authorization Code)”授权类型，这也完全适用于 Logto 的场景。
clientId 和 clientSecret 可以在你的 OIDC 应用详情页找到。
clientId：client ID 是在向授权服务器注册时用于标识客户端应用程序的唯一标识符。授权服务器使用此 ID 验证客户端应用程序的身份，并将任何授权 (Authorization) 的访问令牌 (Access token) 与该特定客户端应用程序关联。
clientSecret：client secret 是授权服务器在注册期间颁发给客户端应用程序的机密密钥。客户端应用程序在请求访问令牌 (Access token) 时使用此密钥向授权服务器进行身份验证。client secret 属于机密信息，必须始终妥善保管。
tokenEndpointAuthMethod：令牌端点认证方法用于客户端应用程序在请求访问令牌 (Access token) 时向授权服务器进行身份验证。要了解支持的方法，请查阅 OAuth 2.0 服务提供商 OpenID Connect 发现端点中的 token_endpoint_auth_methods_supported 字段，或参考 OAuth 2.0 服务提供商的相关文档。
clientSecretJwtSigningAlgorithm（可选）：仅当 tokenEndpointAuthMethod 为 client_secret_jwt 时需要。client secret JWT 签名算法用于客户端应用程序在令牌请求期间对发送给授权服务器的 JWT 进行签名。
scope：scope 参数用于指定客户端应用程序请求访问的一组资源和权限 (Permissions)。scope 参数通常定义为以空格分隔的值列表，代表具体的权限 (Permissions)。例如，scope 值为 "read write" 可能表示客户端应用程序请求对用户数据的读取和写入权限 (Permissions)。
你需要找到 authorizationEndpoint、tokenEndpoint、jwksUri 和 issuer 作为 OpenID Provider 的配置信息。这些信息通常可以在社交厂商的文档中找到。
authenticationEndpoint：此端点用于启动认证 (Authentication) 流程。认证 (Authentication) 流程通常包括用户登录并授权 (Authorization) 客户端应用程序访问其资源。
tokenEndpoint：此端点由客户端应用程序用于获取可用于访问请求资源的 id 令牌 (ID token)。客户端应用程序通常会携带授权类型和授权码向 token 端点发送请求以获取 id 令牌 (ID token)。
jwksUri：这是可以获取社交身份提供商（简称 IdP）的 JSON Web Key Set (JWKS) 的 URL 端点。JWKS 是一组加密密钥，IdP 用于签名和验证在认证 (Authentication) 过程中颁发的 JSON Web Token (JWT)。jwksUri 由依赖方（RP）用于获取 IdP 用于签名 JWT 的公钥，以便 RP 验证从 IdP 接收到的 JWT 的真实性和完整性。
issuer：这是 IdP 的唯一标识符，RP 用于验证从 IdP 接收到的 JWT。它作为 JWT 的 iss 声明 (Claim)（Id token 始终为 JWT）包含在内。issuer 值应与 IdP 授权服务器的 URL 匹配，并且应为 RP 信任的 URI。当 RP 接收到 JWT 时，会检查 iss 声明 (Claim) 以确保其由受信任的 IdP 颁发，并且该 JWT 用于 RP。
jwksUri 和 issuer 共同为 RP 在认证 (Authentication) 过程中验证终端用户身份提供了安全机制。通过使用从 jwksUri 获取的公钥，RP 可以验证 IdP 颁发的 JWT 的真实性和完整性。issuer 值确保 RP 只接受由受信任 IdP 颁发的 JWT，并且这些 JWT 用于 RP。
由于每次都需要认证请求 (Authentication request)，我们提供了 authRequestOptionalConfig 用于包装所有可选配置，详细内容可参考 OIDC 认证请求 (Authentication request)。你可能会注意到此配置中没有 nonce，因为 nonce 应该每次请求都唯一，我们将 nonce 的生成放在代码实现中，所以无需担心！前面提到的 jwksUri 和 issuer 也包含在 idTokenVerificationConfig 中。
你可能会好奇，为什么标准 OIDC 协议支持隐式和混合流，而 Logto 连接器只支持授权码流。经过验证，隐式和混合流的安全性低于授权码流。由于 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 的详细信息请参见 这里。
通用设置
以下是一些不会阻止你连接身份提供商但可能影响终端用户认证 (Authentication) 体验的通用设置。
社交按钮名称和 Logo
如果你希望在登录页面显示社交按钮，可以设置社交身份提供商的名称和Logo（深色模式和浅色模式）。这有助于用户识别社交登录选项。
身份提供商名称
每个社交连接器都有唯一的身份提供商 (IdP) 名称，用于区分用户身份。常见连接器使用固定的 IdP 名称，自定义连接器则需要唯一值。详细了解 IdP 名称。
同步资料信息
在 OIDC 连接器中，你可以设置同步资料信息（如用户名和头像）的策略。可选项包括：
- 仅在注册时同步：用户首次登录时获取一次资料信息。
- 每次登录时都同步：每次用户登录时都会更新资料信息。
存储令牌以访问第三方 API（可选）
如果你希望访问身份提供商的 API 并在用户授权 (Authorization) 下执行操作（无论是通过社交登录还是账户绑定），Logto 需要获取特定 API 权限 (Scopes) 并存储令牌 (Tokens)。
- 按上述说明在 scope 字段中添加所需权限 (Scopes)
- 在 Logto OIDC 连接器中启用为持久 API 访问存储令牌。Logto 会将访问令牌 (Access token) 安全地存储在 Secret Vault 中。
- 对于标准 OAuth/OIDC 身份提供商，必须包含
offline_access权限 (Scope) 以获取刷新令牌 (Refresh token)，防止用户反复授权 (Authorization)。
请妥善保管你的 client secret，切勿在客户端代码中暴露。如果泄露，请立即在身份提供商的应用设置中生成新的 client secret。
使用 OIDC 连接器
创建 OIDC 连接器并连接到你的身份提供商后，你可以将其集成到终端用户流程中。根据你的需求选择相应选项：
启用社交登录按钮
- 在 Logto 控制台，进入 登录体验 > 注册和登录。
- 在社交登录部分添加 OIDC 连接器，让用户通过你的身份提供商进行认证 (Authentication)。
了解更多关于 社交登录体验。
绑定或解绑社交账户
使用 Account API 在你的应用中构建自定义账户中心，让已登录用户绑定或解绑社交账户。参见 Account API 教程
允许仅为账户绑定和 API 访问启用 OIDC 连接器，而不启用社交登录。
访问身份提供商 API 并执行操作
你的应用可以从 Secret Vault 检索存储的访问令牌 (Access token)，调用身份提供商的 API 并自动化后端任务。具体能力取决于你的身份提供商及你请求的权限 (Scopes)。请参考检索存储令牌以访问 API 的指南。
管理用户社交身份
用户绑定社交账户后，管理员可以在 Logto 控制台管理该连接：
- 进入 Logto 控制台 > 用户管理 并打开用户资料页。
- 在社交连接下找到身份提供商项并点击管理。
- 在此页面，管理员可以管理用户的社交连接，查看所有从社交账户授权 (Authorization) 并同步的资料信息，以及检查访问令牌 (Access token) 状态。
部分身份提供商的访问令牌 (Access token) 响应不包含具体权限 (Scope) 信息，因此 Logto 无法直接展示用户授权 (Authorization) 的权限 (Permissions) 列表。但只要用户在授权 (Authorization) 时同意了请求的权限 (Scopes)，你的应用在访问 OIDC API 时就会拥有相应权限 (Permissions)。