使用者遷移

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

選擇遷移策略

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

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

使用者資料結構

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

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

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

保留現有使用者 ID

預設情況下，Logto 會為每個透過 Management API 建立的使用者產生隨機 ID。如果你的應用程式已儲存前一個身分提供者的使用者 ID，可在建立使用者 (create user) 請求主體中傳入選填的 id，以保留原有 ID，避免維護新舊 ID 的對應表。

ID 長度需為 1 至 128 字元，可包含字母、數字及 _ - . @ : + = |。這涵蓋常見格式，如 auth0|5f7c8ec7c33c6c004bbafe82、google-oauth2|103547991597142817347、UUID、user_01H8MZ2QK3V4X5Y6Z7 及電子郵件地址。不允許 URL 路徑中無效字元（空白、/、?、#、%、\），否則會以 400 拒絕，因為 ID 會用於 /api/users/{userId}。若 ID 已被使用，請求會以 422 user.id_already_in_use 失敗。

{
  "id": "auth0|5f7c8ec7c33c6c004bbafe82",
  "primaryEmail": "john.doe@example.com",
  "passwordAlgorithm": "Bcrypt",
  "passwordDigest": "$2b$10$..."
}

備註:

自訂使用者 ID 僅支援自架 Logto。Logto Cloud 若請求帶有 id 會以 501 request.feature_not_supported 拒絕，因為使用者 ID 於租戶間共用。

密碼雜湊

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：期望的雜湊結果（十六進位字串）

範例遷移資料：

{
  "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 租戶
你需要在 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 的一般指引

選擇遷移策略​

使用者資料結構​

保留現有使用者 ID​

密碼雜湊​

一般 Legacy 格式​

PBKDF2 支援​

遷移步驟​

相關資源​