메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.replit.com/llms.txt

Use this file to discover all available pages before exploring further.

앱에 이미 작동하는 인증 시스템과 실제 사용자 데이터베이스가 있는 경우, Clerk Auth를 도입하는 것은 단순한 코드 변경이 아닌 데이터 마이그레이션입니다. 신중한 계획 없이는 users 테이블의 모든 기존 행이 Clerk에게는 낯선 사람이 됩니다: 새 계정이 첫 번째 로그인 시 프로비저닝되고, 기존 데이터와 일치하지 않으며, 기존 고객들이 계정을 “잃어버린” 것처럼 보이게 됩니다. 실제로 올바르게 처리해야 할 사항은 두 가지뿐입니다.
이 페이지는 사용자 정의 인증 솔루션(자체 users 테이블, 비밀번호 해싱, 세션 등)에서 Clerk Auth로 마이그레이션하는 경우만 다룹니다. Replit Auth에서 Clerk Auth로 앱을 이전하기 위한 가이드가 아닙니다 — 해당 마이그레이션 경로에 대한 공식 가이드는 곧 제공될 예정입니다.새 앱을 시작하는 경우 Clerk Auth 개요를 참조하세요 — 마이그레이션이 필요하지 않습니다.

1. 기존 사용자를 Clerk으로 가져오기

앱의 모든 활성 사용자는 Clerk Auth가 활성화되기 전에 Clerk 사용자로 존재해야 합니다. 각 가져오기에는 최소한 다음이 포함되어야 합니다:
  • 이메일 (필수)
  • 사용 가능한 프로필 메타데이터: 이름, 인증 상태, Auth 창에 표시하고 싶은 기타 정보
  • 비밀번호 다이제스트: 사용자의 기존 비밀번호 해시
  • 비밀번호 해셔: Clerk이 기대하는 형식 그대로의 해시 알고리즘/형식
해셔는 잘못 처리하기 쉬운 부분입니다. Clerk은 정의된 비밀번호 해시 형식 세트만 허용하며, 각각 특정 문자열 식별자(bcrypt, scrypt_firebase, argon2i, pbkdf2_sha256 등)를 가집니다. 전체 목록과 각각이 요구하는 정확한 다이제스트 형식은 Clerk Create User API 레퍼런스를 참조하세요. 이 단계는 한 줄짜리 프롬프트 이상이 필요합니다. 마이그레이션을 구동하는 Agent는 현재 코드베이스에서 비밀번호가 어떻게 해싱되는지에 대한 철저한 이해가 필요합니다 — 어떤 라이브러리, 어떤 파라미터(비용 계수, 솔트 레이아웃, 페퍼 등), 그리고 이것이 Clerk의 지원 해셔 중 하나에 어떻게 매핑되는지. 잘 구성된 프롬프트는 다음과 같습니다:
기존 인증 코드를 읽고 비밀번호가 어떻게 해싱되는지 정확히 파악하세요
(라이브러리, 알고리즘, 파라미터, 저장된 값의 형식).
그런 다음 users 테이블의 모든 사용자에 대해
Clerk Backend API를 이메일, 프로필 메타데이터, 매칭되는 Clerk 해셔가 기대하는
정확한 형식의 비밀번호 다이제스트, 그리고 올바른 `passwordHasher` 값으로
호출하는 일회성 가져오기 스크립트를 작성하세요.
실행하기 전에 선택한 Clerk 해셔와 이유를 알려주세요.
해싱 방식이 Clerk의 지원 해셔 중 어느 것에도 깔끔하게 매핑되지 않는 경우, 가져온 사용자들이 기존 비밀번호로 로그인할 수 없게 됩니다. 이 경우 다이제스트 없이 가져오고 전환 시 비밀번호 재설정 이메일을 보내세요.

2. Clerk 사용자를 기존 사용자 ID로 연결

가져온 사용자들이 로그인하면 모든 인증된 요청에 Clerk ID가 포함됩니다. 서버는 해당 ID를 users 테이블의 행에 다시 매핑해야 합니다 — 그렇지 않으면 Clerk 사용자 ID가 기존 외래 키(orders.user_id, documents.owner_id 등)와 일치하지 않아 기록 데이터가 사라진 것처럼 보입니다. Replit 관리 Clerk은 이를 간단하게 만들어줍니다: 기존 ID를 Clerk 사용자의 externalId로 포함하여 사용자를 가져오면, 해당 값이 세션 클레임에 sessionClaims.userId로 자동으로 기록됩니다. 미들웨어는 이를 원시 Clerk 사용자 ID보다 우선시하기만 하면 됩니다:
import { getAuth } from "@clerk/express";

const requireAuth = (req: any, res: any, next: any) => {
  const auth = getAuth(req);
  const userId = auth?.sessionClaims?.userId || auth?.userId;
  if (!userId) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  req.userId = userId;
  next();
};
이 패턴을 사용하면:
  • 가져온 사용자sessionClaims.userId를 통해 기존 users.id로 연결됩니다 — 모든 기록 데이터가 유지됩니다.
  • 새 사용자(전환 후 가입했으며 externalId가 없는 사용자)는 auth.userId로 폴백됩니다. Clerk 사용자 ID를 새 행의 기본 키로 사용하거나, 첫 번째 로그인 시 행을 생성하고 다시 연결하세요.

완료

이외의 모든 것 — 이전 인증을 병렬로 계속 실행하기, 실제 계정에 대한 드라이런 실행하기, 전환 후 중복 사용자 생성 모니터링하기, 이전 시스템 폐기하기 — 은 Clerk Auth에 특화된 것이 아닌 표준 마이그레이션 위생 관리입니다.

추가 리소스