使用者遷移 (User migration)

Logto 支援從其他身分系統批次或即時（Just-in-Time）遷移現有使用者。本指南說明如何透過 Management API 批次匯入使用者，以及遷移前應注意的事項。

選擇遷移策略

策略	適用時機	運作方式
批次遷移 (Bulk migration)	你可以將使用者紀錄與密碼雜湊匯出為 Logto 支援的格式時。	於切換前透過 Management API 匯入使用者，詳見本指南後續步驟。
即時遷移 (Just-in-time migration)	你需要對現有系統驗證密碼、無法匯出相容的密碼雜湊，或希望逐步遷移活躍使用者時。	設定首次驗證後動作 (Post first-factor verification Action)。使用者首次密碼登入時，Logto 透過你的 Action 驗證憑證，建立或更新使用者，並儲存新的本地密碼雜湊。

即時遷移會讓舊有驗證服務持續參與登入請求流程，直到所有使用者完成遷移。請使用快速且穩定的 HTTPS 端點，並於遷移期間保持其可用。

使用者結構 (User schema)

在開始前，先了解 Logto 的使用者結構 (user schema)。你需注意以下三個部分：

基本資料 (Basic data)：來自使用者檔案的基本資訊，可對應你現有的使用者資料。
自訂資料 (Custom data)：儲存額外的使用者資訊，可用於存放無法對應至基本資料的欄位。
社交身分 (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": "john.doe@example.com",
  "passwordAlgorithm": "Legacy",
  "passwordDigest": "[\"pbkdf2\", [\"mySalt123\", \"1000\", \"20\", \"sha512\", \"@\"], \"c465f66c6ac481a7a17e9ed5b4e2e7e7288d892f12bf1c95c140901e9a70436e\"]"
}

遷移步驟

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

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

建立 Logto 租戶 (tenant)
你需要在 Logto 建立一個租戶。可選擇 Logto Cloud 或 Logto OSS。若尚未建立，請參考設定 Logto Cloud 指南。
設定 Management API 連線
我們將透過 Management API 匯入使用者資料，請參考 Management API 了解如何於開發環境設定連線。

匯入使用者資料
建議撰寫腳本逐一匯入使用者資料，將呼叫建立使用者 (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(`匯入使用者 ${user.username} 失敗：${error.message}`);
    }
  }
};

importUsers();

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

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

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

選擇遷移策略​

使用者結構 (User schema)​

密碼雜湊 (Password hashing)​

一般 Legacy 格式​

PBKDF2 支援​

遷移步驟​

相關資源​