Clerk Auth는 Clerk이 제공하는 전용 인증 시스템을 앱에 제공합니다. Replit의 로그인 시스템을 사용하고 Replit 계정을 생성하는 Replit Auth와 달리, Clerk Auth는 앱을 위한 별도의 Clerk 테넌트를 프로비저닝합니다. 앱 사용자는 Replit 계정이 아닌 앱 내에서 직접 계정을 생성하며, 브랜딩, 로그인 방법, 로그인 경험을 완전히 제어할 수 있습니다.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 vs. Replit Auth — Clerk Auth(이 페이지)를 사용하면 앱에 완전히 사용자 정의 가능한 브랜딩과 Replit과 독립적인 사용자 계정을 갖춘 자체 인증 테넌트가 제공됩니다. **Replit Auth**를 사용하면 사용자가 Replit 계정으로 로그인하고 Replit 브랜드의 로그인 페이지를 보게 됩니다. 로그인 경험에 자체 브랜드를 원하거나 Replit과 분리된 사용자 계정이 필요한 경우 Clerk Auth를 선택하세요.
Clerk Auth vs. Replit Auth 한눈에 보기
| Clerk Auth | Replit Auth | |
|---|---|---|
| 사용자 계정 | 사용자가 앱 내에서 계정 생성 (Replit 계정 불필요) | 사용자가 Replit 계정으로 로그인 |
| 브랜딩 | 완전히 사용자 정의 가능 — 앱 이름, 아이콘, 색상 | Replit 브랜드 로그인 페이지 |
| SSO 자격 증명 | 공급자별 자체 OAuth 자격 증명 제공 | Replit의 공유 OAuth 앱 사용 |
| 환경 | 별도의 개발 및 프로덕션 환경 | 단일 환경 |
| 추천 | Replit 추천 통합 없음 | 가입이 Replit 추천에 반영 |
| 최적 사용 사례 | 사용자 정의 브랜드 앱, 전문/상업용 제품 | 빠른 설정, Replit 브랜딩이 허용되는 앱 |
시작하기
앱에 Clerk Auth를 추가하려면 Agent 프롬프트에 포함하세요:Clerk Auth가 Replit에서 작동하는 방식
Agent가 앱에 Clerk Auth를 설정하면:- 전용 Clerk 테넌트 생성 — 앱에 별도의 개발 및 프로덕션 환경을 갖춘 자체 Clerk 애플리케이션이 제공됩니다
- 자격 증명 프로비저닝 — API 키와 시크릿이 환경 변수로 저장됩니다
- 프록시 구성 — 게시된 도메인에서 인증이 원활하게 작동합니다
- 로그인 및 가입 경로 설정 — 사전 구축된 Clerk React 컴포넌트가 앱에 추가됩니다
- 서버 측 미들웨어 추가 — API 경로가 Clerk의 Express 미들웨어로 보호됩니다
Clerk 계정을 생성하거나 인프라를 관리할 필요가 없습니다. 모든 것이 Replit에 의해 자동으로 관리됩니다.
기능
지원되는 기능
Clerk Auth는 앱에 다음을 제공합니다:- 독립적인 사용자 계정 — 앱 사용자는 Replit 사용자가 아니며, 앱의 Clerk 테넌트 내에만 존재합니다
- 완전히 브랜드화된 로그인 페이지 — 앱 이름, 로고, 색상, 폰트 및 로그인/가입 페이지의 문구가 앱 코드에서 구성됩니다
- 사용자 정의 브랜드 SSO — 공급자의 OAuth 동의 화면에 일반 기본값 대신 앱 이름과 브랜딩이 표시되도록 공급자별 OAuth 자격 증명 제공
- 이메일 및 비밀번호 인증 — 이메일 인증을 통한 내장 가입 및 로그인
- 소셜 로그인 (SSO) — 사용자가 Google, GitHub, Apple 또는 X(Twitter)로 로그인 가능
- 사용자 관리 — Auth 창에서 사용자 보기, 검색, 관리
- 세션 처리 — 자동으로 관리되는 보안 세션 토큰
- 개발 및 프로덕션 환경 — 프로덕션 배포 전에 개발에서 인증 테스트
Auth 도구에서 대부분의 Clerk Auth 구성을 관리할 수 있습니다 — Clerk 계정이 필요하지 않으며 Clerk 대시보드를 건드릴 필요가 없습니다.
지원되지 않는 기능
다음 기능은 현재 Clerk Auth에서 사용할 수 없습니다(직접 설정하는 외부 Clerk 앱과 비교). 전체 내역은 이 FAQ를 확인하세요.- 전화번호로 로그인 — SMS 기반 로그인 및 인증
- MFA 지원 — 최종 사용자를 위한 다중 인증
- 전체 SSO 공급자 지원 — 현재 Google, GitHub, Apple, X만 지원
- 조직 테넌트 — Clerk의 조직 및 팀 멤버십 기능
개발 및 프로덕션 환경
Clerk Auth가 있는 모든 앱은 두 개의 완전히 별도의 Clerk 환경을 갖습니다: 빌드하는 동안 개발/미리 보기 앱을 구동하는 개발 환경과 게시된 앱을 구동하는 프로덕션 환경. 이 환경들은 의도적으로 격리되어 있습니다 — 별도의 API 키와 별도의 사용자 저장소를 가집니다.별도의 API 키
각 환경에는 자체 공개 및 비밀 API 키가 있습니다. 앱에 노출되는 키는 앱이 개발에서 실행되는지 프로덕션에서 실행되는지에 따라 자동으로 전환됩니다:- 워크스페이스에서
CLERK_PUBLISHABLE_KEY와CLERK_SECRET_KEY시크릿에는 개발 환경을 가리키는 테스트 키(pk_test...및sk_test...)가 포함됩니다.
- 앱을 게시하면 게시된 배포가 프로덕션 환경을 가리키는 라이브 키(
pk_live...및sk_live...)로 실행됩니다. 접두사를 확인하려면 게시 → 개요 → 설정 조정을 열고CLERK_PUBLISHABLE_KEY와CLERK_SECRET_KEY를 검사하세요.
환경 간 전환을 위해 아무것도 할 필요가 없습니다 — Replit이 개발과 프로덕션 모두에 대한 키를 자동으로 관리합니다. 그냥 개발하고, 테스트하고, 게시하면 됩니다.
별도의 사용자 저장소
각 환경에는 자체 사용자 저장소가 있습니다. 개발 환경에서 가입한 계정은 프로덕션 환경에 존재하지 않으며, 그 반대도 마찬가지입니다:- 개발/미리 보기 앱에서 테스트하면서 가입한 사용자는 개발 저장소에만 생성됩니다.
- 게시된 앱에서 가입한 사용자는 프로덕션 저장소에만 생성됩니다.
- 세션, 사용자 메타데이터, Clerk
userId를 기반으로 한 데이터도 마찬가지로 계정이 생성된 환경에 범위가 지정됩니다.
개발은 실험하고 빌드하는 곳이며, 프로덕션은 라이브 앱의 실제 사용자를 서비스합니다. 둘은 의도적으로 격리되어 있으므로, 개발에서 생성된 계정과 데이터는 프로덕션에 나타나지 않습니다.
사용자 관리
프로젝트 편집기의 Auth 창은 인증된 사용자의 완전한 보기를 제공합니다. Clerk Auth는 앱에 대한 별도의 사용자 저장소를 생성하므로, 여기에 나열된 사용자는 Replit 계정이 아닌 앱의 계정입니다.
- 이메일, 이름, 마지막 로그인, 계정 생성 날짜와 같은 세부 정보와 함께 모든 사용자 보기
- 특정 사용자를 찾기 위한 검색 및 필터
- 앱에 대한 접근을 제어하기 위한 사용자 차단 또는 차단 해제
- 다양한 기준으로 사용자 정렬
- 환경 전환 — 개발과 프로덕션 사이를 토글하여 각 환경의 사용자 관리
로그인 페이지 사용자 정의
로그인 및 가입 페이지의 시각적 브랜딩 — 앱 이름, 로고, 색상, 폰트, 문구 — 은 Auth 창이 아닌 앱 코드에서 구성됩니다. 변경하려면 Agent에게 요청하세요:<ClerkProvider>에 전달되는 appearance 및 localization props와 앱의 public/ 디렉토리에 있는 로고 파일이 이를 구동합니다. Agent가 앱의 테마와 동기화된 상태를 유지합니다.
Google, Apple, GitHub 또는 X의 동의 화면(사용자가 “Google로 로그인” 등을 클릭한 후 나타나는 화면)에 표시되는 앱 이름은 별도입니다 — 해당 공급자에 등록된 OAuth 앱에서 가져오며 로그인 페이지 코드를 편집해도 변경되지 않습니다. 변경하려면 해당 공급자의 사용자 정의 OAuth 자격 증명을 구성하세요.
로그인 공급자 구성
Clerk Auth는 Google, GitHub, Apple, X를 소셜 로그인 공급자로 지원합니다. Auth 창의 구성 탭에서 로그인 페이지에 나타나는 공급자를 제어하고, 프로덕션에서 각 공급자가 Replit 관리 OAuth 자격 증명을 사용할지 아니면 브랜드화된 로그인을 위한 자체 사용자 정의 자격 증명을 사용할지 결정합니다.
- 공급자 활성화 또는 비활성화 — 토글을 사용하여 로그인 페이지에 공급자 표시 여부를 제어합니다. 비활성화된 공급자는 사용자에게 숨겨집니다.
- 사용자 정의 OAuth 자격 증명 구성 (프로덕션 전용) — 아래의 SSO 공급자에 대한 OAuth 자격 증명 구성을 참조하세요.
SSO 공급자에 대한 OAuth 자격 증명 구성
기본적으로 공급자는 Replit 관리 자격 증명을 사용합니다 — 로그인은 즉시 작동하지만 OAuth 동의 화면에 Replit 브랜딩이 표시됩니다. 사용자 정의 자격 증명으로 전환하여 공급자의 개발자 콘솔에서 자체 OAuth 클라이언트를 사용하면 동의 화면에 Replit 브랜딩 대신 앱 이름과 브랜딩이 표시됩니다.- 프로젝트 편집기에서 Auth 창을 엽니다. 구성 탭으로 이동한 다음 사이드바의 SSO 공급자 아래에서 프로덕션을 선택합니다.
- 구성하려는 공급자 옆의 편집 아이콘을 선택합니다. 기본적으로 Replit 관리 자격 증명이 선택되어 있습니다.
- 사용자 정의 자격 증명을 선택합니다. 패널이 확장되어 자격 증명 필드와 공급자 측에서 등록해야 하는 값을 포함한 공급자 설정 체크리스트가 표시됩니다.
- 지침에 따라 구성을 완료합니다. 지침에는 콘솔 및 관련 도우미 문서로의 직접 링크가 포함되어 있습니다. 또한 공급자의 추가 리소스 아래에서 이러한 도우미 문서를 찾을 수 있습니다.
- 필요한 모든 자격 증명 값을 입력합니다.
- 공급자의 개발자 콘솔에서 공급자 개발자 포털의 공급자 설정 체크리스트에 나열된 모든 항목을 등록합니다. 복사 아이콘을 사용하여 각 값을 정확히 복사하고, 완료할 때마다 항목을 체크하거나 완료 시 모두 완료로 표시를 선택합니다.
- 변경 사항 저장을 선택합니다.
도메인 변경 후 설정 재확인
새 외부 도메인을 연결하거나 Replit을 통해 도메인 구매와 같은 도메인 관련 작업은 앱의 리디렉션 콜백 URL과 JavaScript 출처를 변경할 수 있습니다. 이 경우 사용자 정의 자격 증명으로 구성된 공급자는 개발자 콘솔에 새 값을 등록해야 할 수 있습니다. 도메인 변경 후 구성 탭으로 돌아가세요. 설정 알림이 탭, 사이드바, SSO 공급자 목록의 공급자 옆에 경고 아이콘으로 표시됩니다. 공급자 옆의 경고 아이콘과 남은 설정 단계는 해당 공급자의 공급자 설정 체크리스트에 완료해야 할 새 항목이 있음을 의미합니다.
이메일 인증을 위한 도메인 설정
앱에서 이메일 및 비밀번호 가입을 제공하는 경우, Clerk은 각 새 사용자의 받은 편지함에 인증 코드를 보냅니다. 이메일 전송을 위해 도메인을 구성하면 해당 코드가 지연되거나 스팸 필터에 의해 차단되지 않고 앱 URL에서 전송됩니다.이 설정이 필요한 경우
다른 공급자가 관리하는 외부 도메인을 연결하는 경우에만 DNS 레코드를 구성해야 합니다(예: Cloudflare, GoDaddy, Namecheap 또는 유사한 서비스에 등록된 도메인). 다음의 경우에는 설정이 필요하지 않습니다:.replit.app서브도메인- Replit을 통해 구매한 도메인
이메일 발송을 위한 DNS 레코드 추가
외부 도메인에서 인증 이메일을 보내도록 앱을 승인하려면 도메인 공급자에서 DNS 레코드 세트를 추가하세요.- 프로젝트 편집기에서 게시를 엽니다.
- 도메인을 선택합니다.
- 연결된 외부 도메인을 찾아 관리를 선택합니다.
- 인증 DNS 설정 필요 아래에서 Replit이 표시하는 CNAME 레코드를 복사합니다 — 이것이 Clerk이 도메인에서 인증 이메일을 보내는 데 필요한 레코드입니다.
- DNS 공급자(Cloudflare, GoDaddy, Namecheap 등)에 로그인하여 표시된 대로 정확히 각 레코드를 추가합니다.
문제 해결
- 인증 이메일이 도착하지 않음 — 관리 패널에 표시된 대로 정확히 모든 레코드가 추가되었는지 확인하세요(DNS 공급자에서 요구하는 경우 후행 점 포함). 수신자의 스팸 폴더를 확인하세요.
- 레코드가 아직 감지되지 않음 — DNS 전파 시간(최대 48시간)을 기다리고 누락된 것으로 표시된 레코드가 있는지 관리 패널을 다시 확인하세요.
보안 모범 사례
- 항상 서버 측에서 유효성 검사 — UI가 아닌 API 경로에서 인증 확인
- 환경 변수 사용 — 코드에 키나 시크릿을 하드코딩하지 않기
- 프록시 미들웨어를 첫 번째로 유지 — Clerk 프록시는 Express 앱의 본문 파서 앞에 마운트되어야 함
- 홈페이지를 로그인으로 리디렉션하지 않기 — 인증되지 않은 방문자가 랜딩 페이지에 접근할 수 있도록 유지
FAQ
Clerk Auth를 사용하려면 Clerk 계정이 필요한가요?
아니요. Clerk Auth 뒤에 있는 Clerk 테넌트는 Agent가 앱을 설정할 때 Replit에 의해 자동으로 생성 및 관리됩니다 — Clerk에 가입하거나 Clerk 인프라를 직접 관리할 필요가 없습니다.Replit 관리 Clerk 인스턴스의 Clerk 대시보드에 접근할 수 있나요?
아니요. Replit 관리 Clerk 인스턴스는 Clerk 대시보드를 통해 노출되지 않습니다. 대신 프로젝트 편집기의 Auth 도구에서 관리하세요 — 공급자를 구성하고, 사용자를 보고, 개발과 프로덕션 환경 간에 전환하는 곳입니다.Clerk 공개 키가 pk_test로 시작합니다. 라이브 키로 전환하려면 어떻게 해야 하나요?
전환할 필요가 없습니다. 워크스페이스 Secrets 창에서 볼 수 있는 pk_test... 및 sk_test... 키는 앱의 개발 Clerk 환경에 속하며 빌드하는 동안 사용됩니다. 앱을 게시하면 배포가 프로덕션 환경에 대해 pk_live... 및 sk_live... 키로 자동으로 실행됩니다. 확인하려면 워크스페이스에서 게시 → 개요 → 설정 조정을 열고 게시된 앱의 CLERK_PUBLISHABLE_KEY 값을 확인하세요 — pk_live로 시작할 것입니다. 이 키들을 수동으로 편집하지 마세요. 전체 내역은 개발 및 프로덕션 환경을 참조하세요.
개발 중에 만든 계정으로 게시된 앱에 로그인할 수 없는 이유는 무엇인가요?
Clerk Auth의 개발 및 프로덕션 환경에는 별도의 사용자 저장소가 있습니다. 개발/미리 보기 앱에서 만든 계정은 개발 환경에만 존재하며 게시할 때 프로덕션으로 복사되지 않습니다 — 게시된 앱에서 다시 가입해야 합니다. ClerkuserId를 기반으로 한 데이터도 마찬가지입니다. 워크스페이스에서 Auth 창을 열고 사용자 탭의 환경 토글을 사용하여 각 환경의 사용자를 검사하세요. 자세한 내용은 별도의 사용자 저장소를 참조하세요.
Clerk Auth는 무료인가요?
Clerk Auth는 현재 무료입니다. Replit의 다른 사용량 기반 서비스와 마찬가지로 나중에 사용량 기반 가격이 도입될 수 있습니다. 향후 요금은 기존 Replit 청구를 통해 적용될 것이며 — 별도의 Clerk 청구서나 결제 수단이 필요하지 않습니다.Clerk Auth에는 외부 Clerk 플랜과 같은 MAU 제한이 있나요?
아니요. 외부 Clerk 플랜과 달리 Clerk Auth에는 월간 활성 사용자(MAU) 제한이 없습니다.Clerk Auth는 외부 Clerk과 어떻게 비교되나요?
Clerk Auth 뒤에 있는 Replit 관리 Clerk 테넌트는 자체 Clerk 계정에서 만드는 Clerk 앱(외부 Clerk)과 몇 가지 뉘앙스가 있습니다. 아래 표는 현재 두 가지가 어떻게 다른지를 보여줍니다 — 이는 Clerk Auth의 현재 상태를 반영하며 지원되는 기능 세트는 계속 발전할 것입니다.| Clerk Auth | 외부 Clerk | |
|---|---|---|
| 설정 | Replit에 의해 자동 프로비저닝 | 직접 설정 |
| Clerk 테넌트 소유권 | Replit이 관리, 앱이 소유 | 귀하의 Clerk 계정이 소유 |
| 요금 구조 | 현재 무료 (향후 종량제 예정) | 구독 + 종량제 |
| 청구 | Replit 청구 (현재 무료) | Clerk 계정 청구 |
| MAU 제한 | 무제한 | 티어별 제한 |
| 프록시 및 도메인 구성 | replit.app 및 구매한 도메인에 대해 자동, 연결된 도메인은 수동 | 수동 |
| SSO 공급자 | 특정 공급자 지원: Google, Apple, GitHub, X | 더 많은 공급자 지원 |
| 사용자 관리 화면 | 프로젝트 편집기의 Auth 도구 | Clerk 앱 대시보드 |
| SMS | 지원되지 않음 | 지원됨 |
| MFA | 지원되지 않음 | 지원됨 |
| 조직 테넌트 | 지원되지 않음 | 지원됨 |
수동으로 처리해야 하는 일반적인 Clerk Auth 설정은 무엇인가요?
대부분의 Clerk Auth 설정은 자동화되어 있지만, 일부 구성은 Auth 도구 외부에서 조치가 필요합니다:- SSO 공급자의 사용자 정의 OAuth 자격 증명 — 공급자의 동의 화면에 Replit 기본값 대신 앱 이름과 브랜딩이 표시되도록 하려면, 공급자의 개발자 콘솔에서 OAuth 앱을 등록하고 자격 증명을 Auth 창에 붙여넣으세요. SSO 공급자에 대한 OAuth 자격 증명 구성을 참조하세요.
- 외부 도메인의 이메일 인증을 위한 DNS 레코드 — 앱이 다른 공급자가 관리하는 외부 도메인을 연결하는 경우, 도메인에서 인증 이메일이 전송되도록 DNS 레코드를 추가해야 합니다. 이메일 인증을 위한 도메인 설정을 참조하세요.
Replit 관리 Clerk 앱 대신 자체 Clerk 앱을 사용할 수 있나요?
예. 앱에 이미 Replit 관리 Clerk 앱이 프로비저닝되어 있는 경우, 자체 외부 Clerk 앱을 연결하기 전에 먼저 삭제하세요:- 프로젝트 편집기에서 Auth 창을 엽니다.
- 구성 탭으로 이동합니다.
- 페이지 하단으로 스크롤하여 Clerk 앱 삭제를 클릭합니다.
추가 리소스
- Clerk Auth로 기존 앱 마이그레이션 — 기존 사용자 데이터가 있는 비즈니스 앱을 계정 연속성을 유지하며 Clerk Auth로 이동하기 위한 모범 사례
- Google SSO 구성 — Google OAuth 사용자 정의 자격 증명 설정
- GitHub SSO 구성 — GitHub OAuth 사용자 정의 자격 증명 설정
- Apple SSO 구성 — Apple Sign In 사용자 정의 자격 증명 설정
- X (Twitter) SSO 구성 — X OAuth 사용자 정의 자격 증명 설정
- Clerk 문서 — 외부 Clerk 앱을 통합하는 개발자를 위한 레퍼런스