连接器数据结构
介绍
什么是连接器？
连接器 在 Logto 中扮演着关键角色。在它们的帮助下，Logto 使终端用户能够使用无密码注册或登录以及使用社交账户 登录的功能。随着网站和应用程序的日益普及，无密码和社交登录使用户无需管理众多账户和密码。
如果你想设置现有的连接器，请遵循我们的 连接器指南。如果找不到你想要设置的连接器，可以按照 开发你的连接器 中的指南开发这些连接器。
组成部分
连接器数据中有很多属性。
为了提高数据加载和更新的效率，我们将连接器数据的一部分存储在数据库中，这部分数据会经常修改，而其余部分则存储在本地。
- 本地存储，也称为 ConnectorMetadata，是一个包含固定属性的对象，如 logo、连接器类型等。(:face_with_monocle: 对这些属性理解有困难？别担心，详细解释稍后会出现！)
- 远程存储 存储在数据库中，以便对这些数据进行相对频繁的更改。
连接器的本地存储：ConnectorMetadata
id
id 是一个 唯一 的字符串类型的键，用于识别 Logto 中的连接器。
它由每个连接器的开发者分配，并将上传到数据库。
target
target 是一个小写字符串，用于区分社交连接器的社交身份来源。
Logto 用户可以将此变量视为“身份提供商的名称”以便更好地理解。
例如，如果你使用 Google 账户登录日志 (Logto)，你的 target 应该是 google。target 的值可以是任意非空字符串，但我们鼓励你保持简单明了，因为你无法更改它。我们不允许存在具有相同 target 和平台的多个连接器。另一方面，你可以为不同的平台拥有共享相同 target 的社交连接器。例如，如果用户想通过 WeChat 在手机上登录，根据 WeChat 的 TOU，需要一个本地 WeChat 应用程序；同时，还需要一个网络 WeChat 应用程序以启用登录到网络应用程序。这两个 WeChat 应用程序共享相同的身份提供商，并应具有相同的目标。
由于 target 是一个复杂的概念，我们总结了不同的用例和建议供用户参考。
| 示例 | 场景 | 结果 | 推荐吗？ | |
|---|---|---|---|---|
| 不同的 IdP 和不同的 targets | 1. GitHub 连接器 (target: github) 2. Google 连接器 (target: google) | 一个支持使用 GitHub 和 Google 账户登录的应用程序。 | 最常见的用例。 | ✅ |
| 不同的 IdP 和相同的 target | 1. GitHub 连接器 (target: github) 2. Google 连接器 (target: github) | 不适用 | 用户可能会使用另一个用户的 GitHub 账户登录到 Logto 账户。 | ❌ |
| 相同的 IdP 和不同的 targets | 1. GitHub 连接器 (target: github) 2. OAuth GitHub 连接器 (target: github_oauth) | GitHub 连接器用于应用程序 A，而 OAuth GitHub 连接器专为应用程序 B 创建。 | 使用这两个不同的连接器登录到 Logto 将始终创建单独的 Logto 账户，即使用户使用的是相同的 GitHub 账户。 | 分割用户池是唯一需要同时使用两个连接器的场景。然而，通常认为最佳实践是创建两个单独的租户来处理这种用例。 |
| 相同的 IdP 和相同的 target | 1. GitHub 连接器 (target: github) 2. OAuth GitHub 连接器 (target: github) | 不适用 | 使用这两个连接器中的任何一个都可能导致完全相同的结果。 | 创建两个基本上做同样事情的连接器可能会让终端用户感到困惑，并且没有多大意义。最好使用一个适合你特定用例的连接器。 |
type
type 是记录连接器类型的属性。
我们根据功能将连接器定义为三种不同的类型：
- Social：连接器可以在终端用户授权的情况下从任意第三方社交媒体访问用户信息。
- SMS：连接器使终端用户能够在手机上接收短信。
- Email：连接器可以帮助向终端用户发送电子邮件。
platform
platform 用于识别连接器是为哪个平台构建的。
platform 应为 null 或以下字符串类型的值之一：
- Native：仅适用于本地移动应用程序的连接器。
- Web：仅适用于桌面网络应用程序的连接器。
- Universal：可以在移动网络应用程序和桌面网络应用程序上工作的连接器。
email 连接器 和 SMS 连接器 的 platform 应始终为 null。
只有 social 连接器 可以具有非 NULL 的 platform 值。
name
name 是一个对象，其键是 i18n 国家代码，值是连接器的显示名称。
description
description 也是一个对象，其键是 i18n 国家代码，值是连接器的简要描述。
为了支持客户端的 i18n 显示，我们将 name（以及 description）属性存储为一个映射，使用国家代码作为键，使用本地字符的名称（或描述）作为值。
logo
logo 是连接器 logo 的 URL 或相对路径。
logoDark
logoDark 是连接器暗模式 logo 的 nullable URL 或相对路径。
logo 是必需的，而 logoDark 是可选的。
我们在亮模式下显示 logo，如果存在 logoDark，则在暗模式下显示 logoDark。否则将在暗模式下回退显示 logo。
isStandard
isStandard 是一个可选的布尔属性，用于识别社交连接器是否为“标准”连接器。你可以通过其为真值的 isStandard 属性识别“标准”连接器。
Logto 仅支持“标准”社交连接器。也就是说，所有 Logto 的 Email 或 SMS 连接器都不是“标准”的。
Logto 将基于开放和标准协议（例如，OAuth、OIDC、SAML 等）构建的连接器称为“标准”连接器。 Logto 的用户预计将在每个标准连接器上构建多个实例。例如，假设 Logto 已经提供了一个 OAuth 标准连接器，用户可以构建“OAuth GitHub 连接器”、“OAuth Google 连接器”和“OAuth Facebook 连接器”实例。它们都基于 Logto OAuth 标准连接器。
如果你熟悉 Logto 的连接器设计，最多只能同时存在一个 Email 或 SMS 连接器，这意味着 Logto 在当前阶段不需要“标准”的 Email 或 SMS 连接器。
readme
readme 是连接器 README markdown 文件的相对路径，其内容将在连接器设置期间显示在“管理控制台”中。
configTemplate
configTemplate 是连接器配置示例的相对路径。
连接器的远程存储：Connector DB
id
id 作为连接器数据库的主键，是一个随机生成的字符串类型的键，用于识别数据库中的连接器。
connectorId
connectorId 是一个字符串类型的键，是连接 Connector DB 和 ConnectorMetadata 的唯一桥梁。对于每个匹配的连接器数据库数 据和连接器代码模块对，connectorId 始终等于代码模块的 metadata.id。
metadata
metadata 是 ConnectorMetadata 的一个子集，包含可配置的属性，即 logo、logoDark、target 和 name。
syncProfile
syncProfile 是一个布尔值，用于确定用户资料更新方案，默认为 FALSE。
如果 syncProfile 为 FALSE，Logto 用户的基本信息（包括姓名和头像）将仅在用户首次通过此连接器注册到 Logto 时更新。否则，每次用户通过连接器登录到 Logto 时，Logto 账户资料将被更新。
config
config 可以是任意非空对象。
这是连接器存储其配置的地方。每个连接器在 config 中有不同的属性，并且在保存到数据库之前必须是有效的（连接器对“有效”有不同的标准）。只有那些通过有效性检查的 config 才能更新到数据库，否则会抛出错误。
开发人员在开发自己的连接器时需要实现 config 保护，详情请参见 开发你的连接器。
想看看 config 示例吗？请访问 连接器 或每个连接器的设置页面。
在当前 Logto 版本中，同时只能存在一个 Email/SMS 连接器，所有其他具有相同类型的连接器会自动删除。
唯一有效的 Email 或 SMS 连接器规则不适用于 Social 连接器。
换句话说，你可以添加多个 Social 连接器。
createdAt
createdAt 是一个自动生成的时间戳字符串，用于跟踪连接器在数据库中创建的时间。