나만의 UI 가져오기
Logto는 기본 제공 로그인 경험 인터페이스의 사전 제작된 UI 커스터마이즈 옵션 외에도, 여러분만의 UI를 완전히 대체하여 사용할 수 있도록 지원합니다. 이 기능을 통해 여러분은 커스텀 UI 에셋(HTML, CSS, JavaScript, 이미지 등)이 포함된 zip 파일을 업로드하고, Logto Cloud 서버에 호스팅하여 테넌트 사용자의 로그인 경험으로 사용할 수 있습니다.
이 기능은 커스텀 UI가 싱글 페이지 애플리케이션(SPA) 호환이어야 하며, 최적의 성능을 위해 항상 프로덕션 빌드를 사용하는 것이 권장됩니다.
Logto Console에서 커스텀 UI 기능 살펴보기
공식 프로젝트로 시작하기
커스텀 로그인 UI를 가장 빠르게 시작하는 방법은 Logto experience 프로젝트를 클론하는 것입니다. 이 프로젝트는 모든 기능과 Logto의 모범 사례를 포함한 기본 Logto 로그인 경험 UI입니다. 여러분의 필요에 맞게 커스터마이즈할 수 있습니다.
코드를 확인한 후, 아래 명령어를 실행하여 프로젝트를 빌드하세요:
pnpm install && pnpm build
전체 Logto 프로젝트는 pnpm 모노레포입니다. experience 패키지를 단독으로 실행하려면(pnpm 없이), package.json의 workspace: dependencies를 구체적인 버전 번호(예: ^1.0.0)로 교체하세요.
빌드가 완료되면, 모든 컴파일된 에셋이 dist 디렉터리에 생성됩니다. 이후 dist 디렉터리를 ZIP 파일로 압축하세요. 이 파일이 나중에 Logto Cloud에 업로드할 자료가 됩니다.
커스텀 UI 에셋 요구사항
커스텀 UI 에셋을 업로드하기 전에 다음 요구사항을 충족하는지 확인하세요:
- 업로드 자료는 하나의 zip 파일로 압축해야 합니다.
- zip 파일의 루트 디렉터리에
index.html파일이 있어야 합니다. - zip 파일의 크기는 20MB를 초과할 수 없습니다.
- zip 파일 내 개별 파일은 10MB를 초과할 수 없습니다.
- zip 파일 내 전체 파일 수는 200개를 넘을 수 없습니다.
커스텀 UI 에셋 업로드하기
이 기능을 프로덕션 환경에서 사용할 때는 주의하세요. 즉시 사용자의 로그인 경험에 영향을 미칩니다.
-
콘솔 > 로그인 & 계정 > 브랜딩 > 나만의 UI 가져오기
로 이동하세요. - 이전 단계에서 만든 zip 파일을 클릭하여 선택하거나 드래그 앤 드롭하면 업로드가 자동으로 시작됩니다.
- 업로드가 완료되면 변경 사항을 저장하세요. 여러분의 커스텀 UI가 즉시 적용됩니다.
- 커스텀 로그인 UI를 사용할 때는 "로그인 미리보기" 창이 비활성화됩니다. 하지만 "라이브 미리보기" 버튼을 클릭하여 새 브라우저 탭에서 커스텀 로그인 페이지를 테스트할 수 있습니다.
커스텀 CSP 소스 구성하기
Logto는 커스텀 UI 페이지에 Content Security Policy (CSP) 헤더를 적용합니다. 커스텀 UI가 서드파티 스크립트나 외부 서비스에 연결된다면, 콘솔 > 로그인 & 계정 > 브랜딩 > 나만의 UI 가져오기에서 추가 소스 오리진을 등록하세요.
설정 가능한 항목:
script-src: CAPTCHA, 분석, 태그 관리자 등 JavaScript 모듈 또는 스크립트 소스 허용.connect-src:fetch, XMLHttpRequest, EventSource, WebSocket 연결에 사용되는 네트워크 엔드포인트 허용.
예시:
{
"scriptSrc": ["https://scripts.example.com"],
"connectSrc": ["https://api.example.com", "wss://events.example.com"]
}
두 지시어 모두 HTTPS 오리진을 사용하세요. connect-src는 WebSocket 연결을 위해 wss:// 오리진도 허용합니다. Logto는 커스텀 UI 에셋이 활성화된 경우에만 기존 보안 정책에 이 소스를 추가합니다.
Cross-Origin-Opener-Policy 헤더 구성하기
기본적으로 Logto는 Cross-Origin-Opener-Policy (COOP) 헤더를 전송하지 않습니다. 따라서 로그인 페이지를 팝업으로 여는 앱은 window.opener를 통해 계속 통신할 수 있습니다. 앱이 팝업을 통해 사용자를 로그인시키지 않는다면, 커스텀 로그인 UI를 다른 브라우저 창과 격리할 수 있습니다. 콘솔 > 로그인 & 계정 > 브랜딩 > 나만의 UI 가져오기에서 Cross-Origin-Opener-Policy 정책을 선택하세요:
| 옵션 | 전송되는 헤더 | 효과 |
|---|---|---|
| 설정 안 함 (헤더 없음) | 없음 | 기본값. 모든 팝업 기반 연동이 정상 동작합니다. |
same-origin-allow-popups | Cross-Origin-Opener-Policy: same-origin-allow-popups | 로그인 페이지를 연 창과의 연결을 끊습니다. 커스텀 UI가 여는 팝업은 다른 사이트에 머무는 동안 window.opener를 유지합니다. |
same-origin | Cross-Origin-Opener-Policy: same-origin | 커스텀 UI가 여는 팝업도 연결이 끊깁니다. |
또한 로그인 경험 업데이트 Management API의 crossOriginOpenerPolicy 필드로도 설정할 수 있습니다. unsafe-none(기본값, 헤더 미전송), same-origin-allow-popups, same-origin을 지원합니다.
정책을 선택하기 전에, 앱과 커스텀 UI가 팝업을 어떻게 사용하는지 확인하세요:
- 로그인 페이지를 팝업으로 열고
window.opener에 의존하는 앱(예:postMessage로 결과를 받는 경우)은 두 정책 중 하나라도 적용하면 동작하지 않습니다. 이런 앱이 있다면 기본값을 유지하거나, 먼저 리디렉션 기반 로그인 플로우로 전환하세요. - 커스텀 UI가 여는 팝업은 다시 커스텀 UI로 돌아오면(예: 소셜 로그인 콜백 페이지)
window.opener를 잃습니다. 팝업이 다른 사이트에 머무르며 그곳에서 결과를 전송하는 경우(예: 공급자의 자체 로그인 팝업)는same-origin-allow-popups에서 계속 동작합니다.same-origin에서는 팝업이 열리는 즉시window.opener를 잃습니다.
정책이 필요하다면 same-origin보다 same-origin-allow-popups를 권장합니다.
Logto는 커스텀 UI 에셋이 제공되는 동안에만 헤더를 전송합니다. 기본 로그인 페이지, /oidc/* 페이지, Account Center(/account)는 COOP 헤더를 전송하지 않으므로, 보안 스캐너가 해당 페이지에서 누락으로 보고할 수 있습니다.
커스텀 UI 개발하기
Experience API와 상호작용하기
커스텀 UI는 Experience API와 상호작용하여 로그인, 회원가입, 비밀번호 재설정, 소셜 계정 연동, MFA 활성화 등 다양한 작업을 수행해야 합니다. 사용자 플로우와 구현 세부사항을 더 잘 이해하려면, 포괄적인 기술 명세와 예시가 포함된 Experience API 설계 RFC를 참고하세요.
또한, 로그인 경험 API 엔드포인트를 통해 브랜딩 색상, 회사 로고, 파비콘, 비밀번호 정책, 현지화 언어 문구, 커스텀 CSS 등 기타 로그인 경험 설정에도 접근해야 합니다.
CAPTCHA 활성화 시 처리하기
기본 Logto 로그인 경험은 CAPTCHA를 자동으로 처리합니다. 테넌트가 나만의 UI를 사용하고 CAPTCHA 봇 보호를 활성화한 경우, 커스텀 UI는 PUT /api/experience 호출 전에 프론트엔드 CAPTCHA 연동을 완료해야 합니다.
제공자에서 반환된 토큰을 PUT /api/experience 요청 본문의 captchaToken으로 전송하세요. 자세한 내용은 공급자별 가이드를 참고하세요:
샘플 프로젝트
커스텀 UI를 빠르게 이해하고 구현할 수 있도록 다양한 샘플 프로젝트를 제공합니다. 자세한 내용은 Logto Experience project GitHub 저장소를 확인하세요.
또한, 앞으로도 가장 일반적인 사용 사례를 다루는 더 간단하고 시나리오 기반의 샘플 프로젝트를 지속적으로 제공할 예정입니다. 앞으로의 업데이트를 기대해 주세요!
로컬 개발 및 디버깅
로컬 개발 및 디버깅을 위해 Logto Tunnel CLI 도구를 제공합니다:
- 로컬 머신에서 Logto Cloud 엔드포인트로 Experience API 요청 프록시
- 커스텀 UI 구현을 로컬에서 테스트
이를 통해 Logto Cloud에 업로드하기 전에 커스텀 UI를 로컬에서 테스트하고 디버깅할 수 있습니다.
자세한 내용은 커스텀 UI를 로컬에서 디버깅 및 테스트하기를 참고하세요.
CLI로 커스텀 UI 에셋 업로드하기
콘솔을 통한 업로드 외에도, Logto CLI를 사용하여 커스텀 UI 에셋을 업로드할 수 있습니다. 이는 자동화된 배포 워크플로우에 특히 유용합니다.
자세한 내용은 CLI로 커스텀 UI 에셋 업로드하기를 참고하세요.
Logto 기본 로그인 경험으로 복원하기
Logto의 기본 로그인 경험으로 복원하려면, 나만의 UI 카드에서 삭제 버튼을 클릭하세요. 변경 사항을 저장하면 로그인 경험 UI가 Logto의 기본값으로 되돌아갑니다.
관련 리소스
RFCS: Experience API
Experience samples Logto Cloud에 나만의 로그인 UI 가져오기