跳至主要內容

社交連接器開發逐步指南

最快的入門方式是複製一個現有的官方連接器程式碼，並根據你的需求進行修改。以下以 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 換取存取權杖 (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),
  };
};

步驟 3：測試連接器​

單元測試​

首先，撰寫一些單元測試案例，確保基本功能如預期運作。

本地測試​

  • 在本地環境安裝 Logto：Logto 提供多種本地執行方式，你可以使用 CLI、docker，甚至從原始碼建置。詳情請參閱相關文件。
  • 將自訂連接器連結到 Logto 實例：使用 CLI 將你的連接器建立符號連結到 Logto 實例。詳情說明。 
    cd logto
    npx @logto/cli connector link -p .
  • 連結後，你應該能在 <logto-root-path>/packages/core/connectors 資料夾中看到它。
  • 重新啟動 Logto 實例，進入 Logto 管理主控台（Admin Console），你應該能在社交連接器清單中看到它。
  • 在 Console > 登入與帳號 > 註冊與登入 > 社交登入中設定你的連接器。並在我們的 demo app 中使用「即時預覽」功能進行測試。