设置 OAuth 2.0 协议社交登录
官方 Logto OAuth 2.0 协议连接器。
本指南假设你对 Logto 连接器 (Connectors) 有基本的了解。对于不熟悉的人，请参考 连接器 (Connectors) 指南以开始了解。
入门指南
OAuth 连接器让 Logto 能够连接任意支持 OAuth 2.0 协议的社交身份提供商。使用 OAuth 连接器，你的应用可以：
- 添加社交登录按钮
- 将用户账户与社交身份关联
- 从社交提供商同步用户资料信息
- 通过 Logto Secret Vault 安全存储令牌，访问第三方 API，实现自动化任务（如编辑 Google Docs、管理应用内日历事件）
要设置这些认证 (Authentication) 功能，首先需要在 Logto 中创建一个 OAuth 2.0 连接器：
- 前往 Logto 控制台 > 连接器 > 社交连接器。
- 点击 添加社交连接器，选择 OAuth 2.0，点击 下一步，并按照分步教程完成集成。
OAuth 连接器是 Logto 中一种特殊类型的连接器，你可以添加多个基于 OAuth 协议的连接器。
创建你的 OAuth 应用
当你打开此页面时，我们认为你已经知道要连接哪个社交身份提供商。首先要确认该身份提供商是否支持 OAuth 协议，这是配置有效连接器 (Connector) 的前提。然后，按照身份提供商的指引注册并创建用于 OAuth 授权 (Authorization) 的相关应用。
配置你的连接器 (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 字段，或参考 OAuth 2.0 服务提供商提供的相关文档。
clientSecretJwtSigningAlgorithm（可选）：仅当 tokenEndpointAuthMethod 为 client_secret_jwt 时需要。client secret JWT 签名算法用于客户端应用程序在令牌请求期间对发送给授权服务器的 JWT 进行签名。
scope：scope 参数用于指定客户端应用程序请求访问的一组资源和权限 (Permissions)。scope 参数通常定义为以空格分隔的值列表，代表特定权限。例如，scope 值为 "read write" 可能表示客户端应用程序请求对用户数据的读取和写入权限。
你需要在社交厂商的文档中找到 authorizationEndpoint、tokenEndpoint 和 userInfoEndpoint。
authenticationEndpoint：此端点用于启动认证 (Authentication) 流程。认证 (Authentication) 流程通常包括用户登录并授权客户端应用程序访问其资源。
tokenEndpoint：此端点由客户端应用程序用于获取可用于访问所请求资源的访问令牌 (Access token)。客户端应用程序通常向 token 端点发送包含授权类型和授权码的请求，以获取访问令牌 (Access token)。
userInfoEndpoint：此端点由客户端应用程序用于获取有关用户的其他信息，例如全名、电子邮件地址或头像。user info 端点通常在客户端应用程序从 token 端点获取访问令牌 (Access token) 后访问。
Logto 还提供了一个 profileMap 字段，用户可以自定义社交厂商用户资料的映射（通常不是标准格式）。键为 Logto 标准用户资料字段名，对应的值应为社交资料的字段名。目前，Logto 只关注社交资料中的 'id'、'name'、'avatar'、'email' 和 'phone' 字段，其中只有 'id' 是必填项，其他为可选字段。
responseType 和 grantType 只能是授权码授权类型的固定值，因此我们将其设为可选，默认值会自动填充。
例如，你可以查看 Google 用户资料响应，因此其 profileMap 应如下所示：
{
"id": "sub",
"avatar": "picture"
}
我们提供了一个可选的 customConfig 键用于放置你的自定义参数。
每个社交身份提供商在 OAuth 标准协议上可能有自己的变体。如果你所需的社交身份提供商严格遵循 OAuth 标准协议，则无需关心 customConfig。
配置类型
| 名称 | 类型 | 是否必填 |
|---|---|---|
| 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 |
通用设置
以下是一些不会阻止你连接身份提供商，但可能影响终端用户认证 (Authentication) 体验的通用设置。
社交按钮名称和 logo
如果你希望在登录页面显示社交按钮，可以设置社交身份提供商的名称和logo（深色模式和浅色模式）。这将帮助用户识别社交登录选项。
身份提供商名称
每个社交连接器 (Connector) 都有唯一的身份提供商 (IdP) 名称，用于区分用户身份。常见连接器 (Connector) 使用固定的 IdP 名称，自定义连接器 (Connector) 需要唯一值。详细了解 IdP 名称。
同步用户资料信息
在 OAuth 连接器 (Connector) 中，你可以设置同步用户资料（如用户名和头像）的策略。可选项包括：
- 仅在注册时同步：用户首次登录时获取一次资料信息。
- 每次登录时同步：每次用户登录时都会更新资料信息。
存储令牌以访问第三方 API（可选）
如果你希望访问身份提供商的 API 并在用户授权 (Authorization) 下执行操作（无论是通过社交登录还是账号绑定），Logto 需要获取特定 API 权限 (Scopes) 并存储令牌 (Tokens)。
- 按上述说明在 scope 字段中添加所需权限 (Scopes)
- 在 Logto OAuth 连接器 (Connector) 中启用 为持久 API 访问存储令牌。Logto 会将访问令牌 (Access token) 安全地存储在 Secret Vault 中。
- 对于标准 OAuth/OIDC 身份提供商，必须包含
offline_access权限 (Scope) 以获取刷新令牌 (Refresh token)，防止反复弹出用户授权页面 (Consent screen)。
请妥善保管你的 client secret，切勿在客户端代码中暴露。如果泄露，请立即在身份提供商的应用设置中生成新密钥。
使用 OAuth 连接器 (Connector)
创建好 OAuth 连接器 (Connector) 并连接到你的身份提供商后，你可以将其集成到终端用户流程中。根据你的需求选择相应选项：
启用社交登录按钮
- 在 Logto 控制台，前往 登录体验 > 注册与登录。
- 在 社交登录 部分添加 OAuth 连接器 (Connector)，让用户通过你的身份提供商进行认证 (Authentication)。
了解更多关于 社交登录体验。
绑定或解绑社交账号
使用 Account API 在你的应用中构建自定义账号中心，让已登录用户绑定或解绑社交账号。参考 Account API 教程
你可以仅为账号绑定和 API 访问启用 OAuth 连接器 (Connector)，而不启用社交登录。
访问身份提供商 API 并执行操作
你的应用可以从 Secret Vault 检索已存储的访问令牌 (Access token)，调用身份提供商的 API 并自动化后端任务。具体能力取决于你的身份提供商及你请求的权限 (Scopes)。请参考检索存储令牌以访问 API 的指南。
管理用户社交身份
用户绑定社交账号后，管理员可以在 Logto 控制台管理该连接：
- 前往 Logto 控制台 > 用户管理 并打开用户资料。
- 在 社交连接 下找到身份提供商项并点击 管理。
- 在此页面，管理员可以管理用户的社交连接，查看所有从社交账号授权并同步的资料信息，以及检查访问令牌 (Access token) 状态。
部分身份提供商的访问令牌 (Access token) 响应不包含具体权限 (Scope) 信息，因此 Logto 无法直接显示用户授权 (Authorization) 的权限列表。但只要用户在授权 (Authorization) 时同意了所请求的权限 (Scopes)，你的应用在访问 OAuth API 时就会拥有相应权限 (Permissions)。