跳到主要内容

设置 OAuth 2.0 协议社交登录

官方 Logto OAuth 2.0 协议连接器。

提示:

本指南假设你对 Logto 连接器 (Connectors) 有基本的了解。对于不熟悉的人，请参考 连接器 (Connectors) 指南以开始了解。

入门​

OAuth 连接器让 Logto 能够连接到任意支持 OAuth 2.0 协议的社交身份提供商 (IdP)。使用 OAuth 连接器，你的应用可以：

  • 添加社交登录按钮
  • 将用户账户关联到社交身份
  • 从社交提供商同步用户资料信息
  • 通过 Logto Secret Vault 中安全的令牌存储访问第三方 API，实现自动化任务（如编辑 Google Docs、管理应用内的 Calendar 事件）

要设置这些认证 (Authentication) 功能，首先需要在 Logto 中创建一个 OAuth 2.0 连接器：

  1. 前往 Logto 控制台 > 连接器 > 社交连接器。
  2. 点击 添加社交连接器，选择 OAuth 2.0，点击 下一步，并按照分步教程完成集成。
备注:

OAuth 连接器是 Logto 中一种特殊类型的连接器，你可以添加多个基于 OAuth 协议的连接器。

创建你的 OAuth 应用​

当你打开此页面时，我们认为你已经知道要连接哪个社交身份提供商。首先需要确认该身份提供商支持 OAuth 协议，这是配置有效连接器的前提。然后，按照身份提供商的指引注册并创建用于 OAuth 授权的相关应用。

配置你的连接器​

出于安全考虑，我们仅支持 “Authorization Code” 授权类型，这也能完美适配 Logto 的场景。

clientId 和 clientSecret 可以在你的 OAuth 应用详情页找到。

clientId：client ID 是在向授权服务器注册时用于标识客户端应用程序的唯一标识符。授权服务器使用此 ID 验证客户端应用程序的身份，并将任何已授权的访问令牌与该特定客户端应用程序关联。

clientSecret：client secret 是授权服务器在注册期间发放给客户端应用程序的机密密钥。客户端应用程序在请求访问令牌时使用此密钥向授权服务器进行身份验证。client secret 属于机密信息，必须始终妥善保管。

tokenEndpointAuthMethod：令牌端点认证方法用于客户端应用程序在请求访问令牌时向授权服务器进行身份验证。要了解支持的方法，请查阅 OAuth 2.0 服务提供商的 OpenID Connect 发现端点中的 token_endpoint_auth_methods_supported 字段，或参考 OAuth 2.0 服务提供商提供的相关文档。

clientSecretJwtSigningAlgorithm（可选）：仅当 tokenEndpointAuthMethod 为 client_secret_jwt 时需要。client secret JWT 签名算法用于客户端应用程序在令牌请求期间对发送给授权服务器的 JWT 进行签名。

scope：scope 参数用于指定客户端应用程序请求访问的一组资源和权限。scope 参数通常定义为以空格分隔的值列表，代表特定权限。例如，scope 值为 "read write" 可能表示客户端应用程序请求对用户数据的读取和写入权限。

你需要在社交厂商的文档中找到 authorizationEndpoint、tokenEndpoint 和 userInfoEndpoint。

authenticationEndpoint：此端点用于启动认证 (Authentication) 流程。认证 (Authentication) 流程通常包括用户登录并授权客户端应用程序访问其资源。

tokenEndpoint：此端点由客户端应用程序用于获取可用于访问所请求资源的访问令牌。客户端应用程序通常会携带授权类型和授权码向 token 端点发送请求以获取访问令牌。

userInfoEndpoint：此端点由客户端应用程序用于获取有关用户的其他信息，如全名、电子邮件地址或头像。通常在客户端应用程序从 token 端点获取访问令牌后访问 user info 端点。

Logto 还提供了一个 profileMap 字段，用户可以自定义社交厂商用户信息的映射，因为这些信息通常不是标准格式。键为 Logto 标准用户信息字段名，对应的值为社交信息字段名。目前，Logto 只关注社交信息中的 'id'、'name'、'avatar'、'email' 和 'phone' 字段，其中只有 'id' 是必填项，其他为可选项。

responseType 和 grantType 只能是授权码授权类型的固定值，因此我们将其设为可选，默认值会自动填充。

例如，你可以查看 Google 用户信息响应，因此其 profileMap 应如下所示：

{
  "id": "sub",
  "avatar": "picture"
}
备注:

我们提供了一个可选的 customConfig 键用于放置你的自定义参数。 每个社交身份提供商在 OAuth 标准协议上可能有自己的变体。如果你所需的社交身份提供商严格遵循 OAuth 标准协议，则无需关注 customConfig。

配置类型​

名称类型是否必填
authorizationEndpointstringtrue
userInfoEndpointstringtrue
clientIdstringtrue
clientSecretstringtrue
tokenEndpointResponseTypeenumfalse
responseTypestringfalse
grantTypestringfalse
tokenEndpointstringfalse
scopestringfalse
customConfigRecord<string, string>false
profileMapProfileMapfalse
ProfileMap 字段类型是否必填默认值
idstringfalseid
namestringfalsename
avatarstringfalseavatar
emailstringfalseemail
phonestringfalsephone

通用设置​

以下是一些不会阻止你连接身份提供商但可能影响终端用户认证 (Authentication) 体验的通用设置。

如果你希望在登录页面显示社交按钮，可以设置社交身份提供商的名称和logo（深色模式和浅色模式）。这有助于用户识别社交登录选项。

身份提供商名称​

每个社交连接器都有唯一的身份提供商 (IdP) 名称，用于区分用户身份。常见连接器使用固定的 IdP 名称，自定义连接器则需要唯一值。详细了解 IdP 名称。

同步用户信息​

在 OAuth 连接器中，你可以设置同步用户信息（如用户名和头像）的策略。可选项包括：

  • 仅在注册时同步：用户首次登录时获取一次用户信息。
  • 每次登录时同步：每次用户登录时都会更新用户信息。

存储令牌以访问第三方 API（可选）​

如果你希望访问身份提供商的 API 并在用户授权下执行操作（无论是通过社交登录还是账户绑定），Logto 需要获取特定 API scope 并存储令牌。

  1. 按上述说明在 scope 字段中添加所需的权限
  2. 在 Logto OAuth 连接器中启用 为持久 API 访问存储令牌。Logto 会将访问令牌安全地存储在 Secret Vault 中。
  3. 对于标准 OAuth/OIDC 身份提供商，必须包含 offline_access scope 以获取刷新令牌 (Refresh token)，避免反复弹出用户授权。
注意:

请妥善保管你的 client secret，切勿在客户端代码中暴露。如果泄露，请立即在身份提供商的应用设置中生成新密钥。

使用 OAuth 连接器​

创建好 OAuth 连接器并连接到你的身份提供商后，你可以将其集成到终端用户流程中。根据你的需求选择相应选项：

启用社交登录按钮​

  1. 在 Logto 控制台，进入 登录体验 > 注册和登录。
  2. 在 社交登录 部分添加 OAuth 连接器，让用户通过你的身份提供商进行认证 (Authentication)。

了解更多关于 社交登录体验。

使用 Account API 在你的应用中构建自定义账户中心，让已登录用户绑定或解绑他们的社交账号。参考 Account API 教程

提示:

你可以仅为账户绑定和 API 访问启用 OAuth 连接器，无需为社交登录启用。

访问身份提供商 API 并执行操作​

你的应用可以从 Secret Vault 获取已存储的访问令牌，调用身份提供商的 API 并自动化后端任务。具体能力取决于你的身份提供商及你请求的 scope。请参考关于获取存储令牌用于 API 访问的指南。

管理用户社交身份​

用户绑定社交账号后，管理员可以在 Logto 控制台管理该连接：

  1. 进入 Logto 控制台 > 用户管理 并打开用户资料页。
  2. 在 社交连接 下找到身份提供商项并点击 管理。
  3. 在此页面，管理员可以管理用户的社交连接，查看所有从社交账号授权并同步的用户信息，以及检查访问令牌状态。
备注:

部分身份提供商的访问令牌响应不包含具体 scope 信息，因此 Logto 无法直接展示用户授权的权限列表。但只要用户在授权时同意了所请求的 scope，你的应用在访问 OAuth API 时就拥有相应权限。

参考资料​

OAuth 2.0 授权 (Authorization) 框架