본문으로 건너뛰기

나만의 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 > 로그인 & 계정 > 브랜딩 > 나만의 UI 가져오기

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

사용자 정의 CSP 소스 설정하기​

Logto는 사용자 정의 UI 페이지에 Content Security Policy (CSP) 헤더를 적용합니다. 사용자 정의 UI가 타사 스크립트를 로드하거나 외부 서비스에 연결해야 한다면 Console > 로그인 & 계정 > 브랜딩 > 나만의 UI 가져오기에서 추가로 허용할 origin을 설정하세요.

다음을 설정할 수 있습니다:

  • script-src: CAPTCHA, analytics, tag manager 제공자와 같은 JavaScript module 또는 script 소스를 허용합니다.
  • connect-src: fetch, XMLHttpRequest, EventSource, WebSocket 연결에서 사용하는 네트워크 엔드포인트를 허용합니다.

예시:

{
  "scriptSrc": ["https://scripts.example.com"],
  "connectSrc": ["https://api.example.com", "wss://events.example.com"]
}

두 directive 모두 HTTPS origin을 사용하세요. WebSocket 연결의 경우 connect-src는 wss:// origin도 허용합니다. Logto는 사용자 정의 UI 에셋이 활성화된 경우에만 이러한 소스를 기존 보안 정책에 추가합니다.

사용자 정의 UI 개발하기​

Experience API와 상호작용하기​

사용자 정의 UI는 Experience API와 상호작용하여 로그인, 회원가입, 비밀번호 재설정, 소셜 계정 연동, MFA 활성화 등 다양한 작업을 수행해야 합니다. 사용자 흐름과 구현 세부사항을 더 잘 이해하려면, 포괄적인 기술 사양과 예시가 포함된 Experience API 디자인 RFC를 참고하는 것이 좋습니다.

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

CAPTCHA 활성화 시 처리하기​

기본 Logto 로그인 경험은 CAPTCHA를 자동으로 처리합니다. 테넌트가 나만의 UI 가져오기와 CAPTCHA 봇 보호를 함께 사용할 경우, 사용자 정의 UI는 PUT /api/experience 호출 전에 프론트엔드 CAPTCHA 연동을 완료해야 합니다.

제공자 토큰을 captchaToken으로 하여 PUT /api/experience 요청 본문에 전달하세요. 자세한 내용은 제공자별 가이드를 참고하세요:

샘플 프로젝트​

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

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

로컬 개발 및 디버깅​

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

  • 로컬 머신에서 Logto Cloud 엔드포인트로 Experience API 요청 프록시
  • 사용자 정의 UI 구현을 로컬에서 테스트

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

자세한 내용은 로컬에서 사용자 정의 UI 디버그 및 테스트하기를 참고하세요.

CLI를 사용하여 사용자 정의 UI 에셋 업로드하기​

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

자세한 내용은 CLI를 사용한 사용자 정의 UI 에셋 업로드를 참고하세요.

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

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

RFCS: Experience API

 Experience 샘플 Logto Cloud에 나만의 로그인 UI 가져오기