跳到主要内容

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

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

第一步：克隆一个现有的连接器包​

在一个连接器的源码文件夹中，你会看到以下文件：

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

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

第二步：修改主入口文件（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 换取访问令牌 (Access token)。
  • getUserInfo：使用访问令牌 (Access token) 从第三方社交平台获取用户信息。

大多数其他通用逻辑已经在 Logto 连接器工具包中处理好了，这会让你的开发工作更加轻松。

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

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

第三步：测试连接器​

单元测试​

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

本地测试​

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