사용자 마이그레이션

Logto는 기존 아이덴티티 시스템에서 기존 사용자를 일괄 또는 Just-in-Time 방식으로 마이그레이션하는 것을 지원합니다. 이 가이드에서는 Management API를 통해 사용자를 일괄로 가져오는 방법과 마이그레이션 전에 고려해야 할 사항을 설명합니다.

마이그레이션 전략 선택하기

전략	선택 시기	작동 방식
일괄 마이그레이션	사용자 레코드와 비밀번호 해시를 Logto가 지원하는 형식으로 내보낼 수 있을 때.	이 가이드의 나머지 부분을 따라 Management API를 통해 전환 전에 사용자를 가져옵니다.
Just-in-Time 마이그레이션	기존 시스템에서 비밀번호를 검증해야 하거나, 호환 가능한 비밀번호 해시를 내보낼 수 없거나, 활성 사용자를 점진적으로 마이그레이션하고 싶을 때.	Post first-factor verification Action을 구성하세요. 사용자가 처음으로 비밀번호로 로그인할 때, Logto는 Action을 통해 자격 증명을 검증하고, 사용자를 생성 또는 업데이트하며, 새로운 로컬 비밀번호 해시를 저장합니다.

Just-in-Time 마이그레이션은 사용자가 마이그레이션될 때까지 기존 인증 (Authentication) 서비스를 로그인 요청 경로에 유지합니다. 빠르고 신뢰할 수 있는 HTTPS 엔드포인트를 사용하고, 마이그레이션 기간 동안 이를 사용할 수 있도록 하세요.

사용자 스키마

시작하기 전에, Logto의 사용자 스키마를 살펴보겠습니다. 사용자 스키마에는 알아야 할 3가지 부분이 있습니다:

기본 데이터: 사용자 프로필의 기본 정보로, 기존 사용자 프로필의 데이터를 매칭할 수 있습니다.
커스텀 데이터: 추가 사용자 정보를 저장하며, 기본 데이터와 매칭할 수 없는 파일을 저장하는 데 사용할 수 있습니다.
소셜 아이덴티티: 소셜 로그인에서 가져온 사용자 정보를 저장합니다.

기존 사용자 프로필의 정보를 기본 데이터와 커스텀 데이터에 매핑하는 맵을 만들 수 있습니다. 소셜 로그인에 대해서는 소셜 아이덴티티를 가져오기 위한 추가 단계가 필요하며, 자세한 내용은 사용자에 소셜 아이덴티티 연결 API를 참고하세요.

비밀번호 해싱

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');
// 'salt123' + 'password123'를 해싱
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: 16진수 문자열로 된 기대 해시 결과

마이그레이션 예시 페이로드:

{
  "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로 마이그레이션하는 일반 가이드라인

마이그레이션 전략 선택하기​

사용자 스키마​

비밀번호 해싱​

일반 Legacy 포맷​

PBKDF2 지원​

마이그레이션 단계​

관련 리소스​