跳至主要內容

開發社交連接器的逐步指南

最快的入門方式是複製現有的官方連接器代碼並修改以符合你的需求。我們以 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 管理控制台，你應該能在社交連接器列表中看到它。
  • 在 控制台 > 登入體驗 > 註冊和登入 > 社交登入中配置你的連接器。並在我們的示範應用程式中使用「即時預覽」功能進行嘗試。