跳到主要内容

开发社交连接器的分步指南

最快的入门方法是复制现有官方连接器的代码，并根据你的需求进行修改。我们以 GitHub 连接器为例。

步骤 1：克隆现有的连接器包​

在连接器的源文件夹中，你会找到以下文件：

  • index.ts：连接器的主入口文件。
  • constant.ts：连接器中使用的常量。
  • types.ts：连接器中使用的 TypeScript 类型。
  • index.test.ts：连接器的测试用例。
  • mock.ts：连接器测试用例中使用的模拟数据。

除了这些文件，你还需要提供一个 README.md 文件来描述连接器，一个 logo.svg（可选的 logo-dark.svg 用于更好的暗模式用户体验），以及一个 package.json 文件来定义 npm 包信息。

步骤 2：修改主入口文件（index.ts）​

在 index.ts 文件中，你会找到大部分连接器逻辑。通常你需要实现以下 4 个函数：

  • getAuthorizationUri：生成第三方社交平台的授权 URI。对于 GitHub，它是：https://github.com/login/oauth/authorize?client_id={clientId}&redirect_uri={redirectUri}&state={state}。请参考目标社交平台的开发者文档以获取正确的 URI。
  • authorizationCallbackHandler：保护授权回调 URI 中返回的参数值，提取授权 code 并处理潜在的错误。
  • getAccessToken：将授权 code 交换为访问令牌。
  • getUserInfo：使用访问令牌从第三方社交平台获取用户信息。

大多数其他常见逻辑已经在 Logto 连接器工具包中处理，这将使你的工作更轻松。

最后，在文件末尾，你只需按照与 GitHub 连接器相同的代码结构导出连接器对象。

const createGithubConnector: CreateConnector<SocialConnector> = async ({ getConfig }) => {
  return {
    metadata: defaultMetadata,
    type: ConnectorType.Social,
    configGuard: githubConfigGuard,
    getAuthorizationUri: getAuthorizationUri(getConfig),
    getUserInfo: getUserInfo(getConfig),
  };
};

步骤 3：测试连接器​

单元测试​

首先，编写一些单元测试用例，确保基本功能按预期工作。

本地测试​

  • 在本地环境中设置 Logto：Logto 提供了几种本地运行的方法，你可以使用 CLI，或者 docker，甚至从源代码构建。查看文档以获取 更多详情。
  • 将你的自定义连接器链接到你的 Logto 实例：使用 CLI 创建你的连接器到 Logto 实例的符号链接。更多详情。 
    cd logto
    npx @logto/cli connector link -p .
  • 链接连接器后，你应该能在 <logto-root-path>/packages/core/connectors 文件夹中看到它。
  • 重启你的 Logto 实例，进入 Logto 管理控制台，你应该能在社交连接器列表中看到它。
  • 在 控制台 > 登录体验 > 注册和登录 > 社交登录中配置你的连接器。并在我们的演示应用中使用“实时预览”功能进行尝试。