오토위니 서비스에 Keycloak을 도입하며 로그인 화면 커스터마이징을 진행했습니다. 국내 자료가 부족해 구현 과정에서 겪었던 경험과 Keycloakify를 통해 15개국 다국어 대응을 완료한 과정을 공유합니다.
Keycloakify 선정 이유
Keycloak 로그인 화면은 기본적으로 FTL(FreeMarker Template Language) 문법을 사용합니다. 하지만 추후 프로젝트의 유지보수를 고려해 Keycloakify 프레임워크를 선택했습니다.
가장 큰 이유는 팀원들에게 익숙한 React(JSX) 문법을 그대로 사용할 수 있다는 점이었습니다. 러닝 커브를 줄이고 기존에 사용하던 라이브러리들을 활용할 수 있어 개발 생산성 측면에서 유리하다고 판단했습니다.
1. 클라이언트별 테마 분기 (clientId)
단일 프로젝트 내에서 clientId를 식별자로 사용하여 관리자(Admin)와 일반 사용자(Web)의 UI를 분기 처리했습니다.
- 관리자 (autowini-admin): 300px 너비의 컴팩트한 다크 테마 UI를 적용했습니다.
- 서비스 웹 (autowini-web): 360px 너비의 라이트 테마와 Floating Label 애니메이션을 적용했습니다. (상품 상세 페이지에서 리다이렉트된 경우를 감지하여 '멤버십 안내 박스'가 노출되도록 구현했습니다.)
2. 15개국 다국어(i18n) 처리와 트러블슈팅
오토위니는 15개국어를 지원해야 하지만, Keycloakify 기본 시스템만으로는 대응이 어려운 부분이 있었습니다.
문제 상황:
- 미지원 언어: az, sw, km, my, mn 등 일부 언어가 Keycloakify 기본 라이브러리에 포함되어 있지 않았습니다.
- 언어 설정 초기화: 로그인 실패 시 페이지가 새로고침되면서 URL의 ui_locales 파라미터가 유실되어 언어가 다시 영어(en)로 돌아가는 문제가 있었습니다.
해결 방법: 기본 시스템 대신 i18next를 별도로 구성하고 SessionStorage를 활용했습니다. URL에서 읽어온 언어 코드를 세션에 저장하여, 새로고침 이후에도 사용자가 선택한 언어가 유지되도록 처리했습니다.
3. Storybook 활용 경험
기존에도 Storybook의 존재는 알고 있었지만, 실제 개발 과정에서 굳이 도입할 필요성을 크게 느끼지 못했습니다. 하지만 이번 프로젝트를 진행하며 그 효용성을 직접 체감하게 되었습니다.
Keycloakify 프로젝트를 포크(Fork)하여 내부의 Storybook 환경을 적극 활용해 보니, 매번 코드를 수정하거나 상태 값을 직접 변경하지 않아도 다양한 케이스를 즉각적으로 확인할 수 있는 점이 매우 편리했습니다.
특히 Keycloak 서버를 직접 실행하지 않고도 에러 메시지 노출이나 재인증 플로우 같은 특정 시나리오를 즉시 시뮬레이션할 수 있어 개발 속도가 크게 향상되었습니다. 초기에 환경을 구축하는 과정은 다소 번거로울 수 있지만, 한 번 구축해두면 디버깅 시간을 단축하고 전체적인 완성도를 높이는 데 큰 도움이 된다는 점을 배웠습니다.
느낌 점
이번 과정의 핵심은 Keycloak 인증 시스템 도입에 맞춰 프론트엔드 팀이 로그인 페이지 개발부터 참여하며 최적의 구현 방식을 결정한 데 있었습니다.
처음에는 기본 문법인 FTL(FreeMarker Template Language) 사용을 검토했으나, R&D를 통해 Keycloakify를 도입하기로 결정했습니다. 이를 통해 익숙한 React 문법을 활용할 수 있었고 개발 효율을 크게 높일 수 있었습니다.
또한 초기에는 관리자와 웹 프로젝트를 각각 분리하여 관리하려 했으나, 운영 효율과 유지보수성을 고려해 단일 프로젝트 내에서 관리하는 구조로 설계했습니다. 덕분에 공통 컴포넌트와 비즈니스 로직을 효율적으로 공유하며 확장성을 확보할 수 있었습니다.
국내 자료가 적어 구축 과정에서 어려움이 있었지만, 결과적으로 Keycloakify와 React의 조합으로 안정적인 인증 시스템을 구축했습니다. Keycloak 커스텀 페이지 개발을 고민하시는 분들께 이 기록이 조금이나마 도움이 되길 바랍니다.
구현 과정이나 상세 로직에 대해 궁금하신 점이 있다면 댓글로 남겨주세요. 아는 선에서 자세히 답변드리겠습니다!
'지식 정리 📝' 카테고리의 다른 글
| Frontend Kit – AI 문답 기능 도입 (Gemma 3 27B) (0) | 2026.02.27 |
|---|---|
| WiniLogis Webpack에서 Vite로 마이그레이션 (2) | 2026.02.10 |
| Lighthouse 90점대인데 체감은 느린 이유? Vercel Region 최적화로 해결 (2) | 2026.02.03 |
| Autowini 프론트엔드 분리 프로젝트 CI/CD 파이프라인 구축 (Bitbucket 기반) 2 (0) | 2026.01.19 |
| 필터 변경 시 메뉴가 접히던 문제, TanStack Query placeholderData로 해결 (2) | 2026.01.15 |