跳至主要內容

使用者遷移 (User migration)

Logto 支援從其他平台手動遷移現有使用者。本指南將說明如何透過 Management API 匯入現有使用者，以及遷移前你應考慮的事項。

使用者結構 (User schema)​

在開始之前，讓我們先看看 Logto 的 使用者結構。你需要注意使用者結構的三個部分：

  1. 基本資料 (Basic data)：來自使用者檔案的基本資訊，你可以將現有使用者檔案的資料對應到這裡。
  2. 自訂資料 (Custom data)：儲存額外的使用者資訊，可用於存放無法對應到基本資料的欄位。
  3. 社交身分 (Social identities)：儲存從社交登入取得的使用者資訊。

你可以建立對照表，將現有使用者檔案的資訊對應到 基本資料 (basic data) 與 自訂資料 (custom data)。若有社交登入，需額外步驟匯入社交身分，請參考 連結社交身分至使用者 (Link social identity to user) 的 API。

密碼雜湊 (Password hashing)​

Logto 使用 Argon2 進行使用者密碼雜湊，並為遷移方便支援其他演算法，如 MD5、SHA1、SHA256 及 Bcrypt。這些演算法被認為不安全，對應的密碼雜湊值會在使用者首次成功登入時自動遷移為 Argon2。

如果你使用其他雜湊演算法或加鹽，可以將 passwordAlgorithm 設為 Legacy，這允許你使用 Node.js 支援的任何雜湊演算法。支援的演算法列表可參考 Node.js crypto 文件。此情況下，passwordDigest 需為包含雜湊演算法及其他參數的 JSON 字串。

一般 Legacy 格式​

JSON 字串格式如下：

["hash_algorithm", ["argument1", "argument2", ...], "expected_hashed_value"]

你可以用 @ 作為實際密碼值的佔位符。

例如，若你使用 SHA256 並加鹽，可如下儲存密碼：

["sha256", ["salt123", "@"], "c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e"]

這等同於以下程式碼：

const hash = crypto.createHash('sha256');
hash.update('salt123' + 'password123');
const expectedHashedValue = hash.digest('hex');

PBKDF2 支援​

Logto 特別支援 PBKDF2。

若要遷移 PBKDF2 雜湊的密碼，請將 passwordAlgorithm 設為 Legacy，並將 passwordDigest 格式化如下：

["pbkdf2", ["salt", "1000", "20", "sha512", "@"], "expected_hashed_value"]

參數說明：

  • salt：原始雜湊時使用的鹽值
  • iterations：迭代次數（如 "1000"）
  • keylen：導出金鑰長度（位元組，例 "20"）
  • digest：使用的雜湊函式（如 "sha512"、"sha256"、"sha1"）
  • @：實際密碼值的佔位符
  • expected_hashed_value：預期的雜湊結果（十六進位字串）

範例遷移 payload：

{
  "username": "john_doe",
  "primaryEmail": "[email protected]",
  "passwordAlgorithm": "Legacy",
  "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]"
}

遷移步驟 (Steps to migrate)​

  1. 準備使用者資料 你應先從現有平台匯出使用者資料，並將資訊對應到 Logto 的使用者結構。我們建議你將對應後的資料整理為 JSON 格式。以下為範例：

    [
      {
        "username": "user1",
        "passwordDigest": "password-encrypted",
        "passwordAlgorithm": "SHA256"
      },
      {
        "username": "user2",
        "passwordDigest": "password-encrypted",
        "passwordAlgorithm": "SHA256"
      }
    ]

  2. 建立 Logto 租戶 (tenant) 你需要在 Logto 建立一個租戶。可選擇 Logto Cloud 或 Logto OSS。若尚未建立，請參考 設定 Logto Cloud 指南。

  3. 設置 Management API 連線 我們將使用 Management API 匯入使用者資料，請參考 Management API 了解如何在開發環境設置連線。

  4. 匯入使用者資料 建議你撰寫腳本逐一匯入使用者資料，將呼叫 建立使用者 (create user) API。以下為腳本範例：

    const users = require('./users.json');

    const importUsers = async () => {
      for (const user of users) {
        try {
          await fetch('https://[tenant_id].logto.app/api/users', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              Authorization: 'Bearer [your-access-token]',
            },
            body: JSON.stringify(user),
          });
          // 為避免觸發速率限制，請暫停一段時間
          await new Promise((resolve) => setTimeout(resolve, 200));
        } catch (error) {
          console.error(`Failed to import user ${user.username}: ${error.message}`);
        }
      }
    };

    importUsers();

請注意，API 端點有速率限制，請於每次請求間加入暫停以避免觸發限制。詳情請參閱 速率限制 頁面。

若你有大量使用者資料（10 萬以上），可聯絡我們以提升速率限制。

將現有使用者資料庫遷移至 Logto 的一般指引