본문으로 건너뛰기

나만의 UI 적용하기

Logto는 기본 제공 로그인 경험 인터페이스의 사전 제작된 UI 커스터마이즈 옵션 외에도, 여러분이 직접 만든 UI로 완전히 대체할 수 있도록 지원합니다. 이 기능을 통해 여러분은 커스텀 UI 에셋(HTML, CSS, JavaScript, 이미지 등)이 포함된 zip 파일을 업로드하고, Logto Cloud 서버에 호스팅하여 테넌트 사용자의 로그인 경험으로 사용할 수 있습니다.

노트:

이 기능은 커스텀 UI가 Single Page Application (SPA) 호환이어야 하며, 최적의 성능을 위해 항상 프로덕션 빌드를 사용하는 것이 권장됩니다.

Logto Console에서 커스텀 UI 기능 살펴보기​

공식 프로젝트로 시작하기​

커스텀 로그인 UI를 가장 빠르게 시작하는 방법은 Logto experience 프로젝트를 클론하는 것입니다. 이 프로젝트는 모든 기능과 Logto의 모범 사례를 담은 기본 Logto 로그인 경험 UI입니다. 여러분의 필요에 맞게 커스터마이즈할 수 있습니다.

코드를 확인한 후, 아래 명령어를 실행하여 프로젝트를 빌드하세요:

pnpm install && pnpm build
노트:

전체 Logto 프로젝트는 pnpm 모노레포입니다. experience 패키지를 단독으로 실행하고 싶다면(pnpm 없이), package.json의 workspace: 의존성을 특정 버전(예: ^1.0.0)으로 교체하세요.

빌드가 완료되면, 모든 컴파일된 에셋이 dist 디렉터리에 생성됩니다. 이후 dist 디렉터리를 ZIP 파일로 압축하세요. 이 압축 파일은 나중에 Logto Cloud에 업로드하는 데 사용됩니다.

커스텀 UI 에셋 요구사항​

커스텀 UI 에셋을 업로드하기 전에 다음 요구사항을 충족하는지 확인하세요:

  • 업로드할 에셋은 하나의 zip 파일로 압축해야 합니다.
  • zip 파일의 루트 디렉터리에 index.html 파일이 있어야 합니다.
  • zip 파일 크기는 20MB를 초과할 수 없습니다.
  • zip 파일 내 단일 파일 크기는 10MB를 초과할 수 없습니다.
  • zip 파일 내 전체 파일 수는 200개를 넘을 수 없습니다.

커스텀 UI 에셋 업로드하기​

노트:

이 기능을 프로덕션 환경에서 사용할 때는 신중히 진행하세요. 즉시 사용자의 로그인 경험에 영향을 미칩니다.

  1. Console > Sign-in & account > Branding > Bring your UI

     로 이동하세요.
  2. 이전 단계에서 만든 zip 파일을 클릭하여 선택하거나 드래그 앤 드롭하면 업로드가 자동으로 시작됩니다.
  3. 업로드가 완료되면 변경 사항을 저장하세요. 여러분의 커스텀 UI가 즉시 적용됩니다.
  4. 커스텀 로그인 UI를 사용할 경우 "Sign-in preview" 창은 비활성화됩니다. 하지만 "Live preview" 버튼을 클릭하여 새 브라우저 탭에서 커스텀 로그인 페이지를 테스트할 수 있습니다.

커스텀 UI 개발하기​

Experience API와 상호작용하기​

여러분의 커스텀 UI는 Experience API와 상호작용하여 로그인, 회원가입, 비밀번호 재설정, 소셜 계정 연동, MFA 활성화 등 다양한 작업을 수행해야 합니다. 사용자 플로우와 구현 세부사항을 더 잘 이해하려면, 포괄적인 기술 사양과 예시가 담긴 Experience API design RFC를 참고하는 것을 추천합니다.

또한, sign-in Experience API endpoint를 통해 브랜딩 색상, 회사 로고, 파비콘, 비밀번호 정책, 현지화 언어 문구, 커스텀 CSS 등 기타 로그인 경험 설정에도 접근해야 합니다.

샘플 프로젝트​

커스텀 UI를 빠르게 이해하고 구현할 수 있도록 다양한 샘플 프로젝트를 제공합니다. 자세한 내용은 Logto Experience project GitHub 저장소를 확인하세요.

또한, 가장 일반적인 사용 사례를 다루기 위해 더 간단하고 시나리오 기반의 샘플 프로젝트도 계속 제공할 예정입니다. 앞으로의 업데이트를 기대해 주세요!

로컬 개발 및 디버깅​

로컬 개발 및 디버깅을 위해 Logto Tunnel CLI 도구를 제공합니다:

  • 로컬 머신에서 Logto Cloud 엔드포인트로 Experience API 요청을 프록시합니다.
  • 커스텀 UI 구현을 로컬에서 테스트할 수 있습니다.

이를 통해 Logto Cloud에 업로드하기 전에 커스텀 UI를 로컬에서 테스트하고 디버깅할 수 있습니다.

자세한 내용은 커스텀 UI를 로컬에서 디버깅 및 테스트하기를 참고하세요.

CLI를 사용하여 커스텀 UI 에셋 업로드하기​

Console을 통한 업로드 외에도, Logto CLI를 사용하여 커스텀 UI 에셋을 업로드할 수 있습니다. 이는 자동화된 배포 워크플로우에 특히 유용합니다.

자세한 내용은 CLI를 사용하여 커스텀 UI 에셋 업로드하기를 참고하세요.

Logto 기본 로그인 경험으로 복원하기​

Logto의 기본 로그인 경험으로 복원하려면 Bring your UI 카드에서 삭제 버튼을 클릭하세요. 변경 사항을 저장하면 로그인 경험 UI가 Logto의 기본값으로 되돌아갑니다.

RFCS: Experience API

 Experience 샘플 Logto Cloud에 나만의 로그인 UI 적용하기