Devops
Keycloak
테마 및 UI 커스터마이징

테마 및 UI 커스터마이징

1️⃣ 로그인/계정 화면 커스터마이징

1. Keycloak 기본 로그인 화면

Keycloak은 기본적으로 아래와 같은 로그인 화면을 제공합니다.

✅ 장점

  • 즉시 사용 가능
  • 반응형 디자인
    ❌ 단점
  • 회사 CI / UX에 맞지 않음

2. 로그인 화면 커스터마이징 개요

커스터마이징 가능한 화면 종류는 다음과 같습니다:

화면 설명
login 로그인, OTP, 에러 등
account 마이 페이지 (비밀번호 변경, 이메일 확인 등)
email 인증 메일 HTML
welcome 기본 Keycloak 시작 화면

3. 화면 커스터마이징 방법 요약 

<KEYCLOAK_HOME>/themes/mytheme/
├── login/
├── account/
├── email/
├── theme.properties
└── resources/
# theme.properties
parent=keycloak
import=common

Keycloak 서버 실행 시 standalone.conf에 테마 경로 지정:

export KEYCLOAK_THEME=mytheme

또는 realm에서 직접 설정:

Admin Console > Realm Settings > Themes

4. 예시: 로그인 페이지 제목 바꾸기

themes/mytheme/login/login.ftl

<h1>🚀 회사 전용 로그인 포털</h1>

2️⃣ Freemarker 템플릿 구조

1. Freemarker란?

Keycloak의 테마는 Apache FreeMarker 템플릿 엔진을 사용합니다.
HTML + 변수 치환 방식으로 동작하며, 조건문/반복문 등도 사용 가능.

2. 주요 템플릿 파일

파일명 설명
login.ftl 기본 로그인 페이지
login-update-password.ftl 비밀번호 초기화 화면
login-verify-email.ftl 이메일 인증 화면
message.ftl 일반 메시지 화면 (예: 로그아웃됨)

3. 예시: 로그인 페이지에 사용자 안내 문구 추가 

<p>로그인 후 내부 시스템을 이용하실 수 있습니다.</p>
<#if realm.password && usernameEditDisabled?? && usernameEditDisabled>
  <p>비밀번호 인증만 가능합니다.</p>
</#if>

4. 커스터마이징 플로우 

[ 사용자의 웹 요청 ]
       ↓
[ Keycloak Theme Resolver ]
       ↓
[ mytheme/login/login.ftl 렌더링 ]
       ↓
[ Freemarker + HTML + CSS ]
       ↓
[ 사용자에게 응답 ]

3️⃣ 커스텀 로고, 색상, 레이아웃 설정

1. 로고 및 스타일 파일 위치 

themes/mytheme/resources/img/logo.png
themes/mytheme/resources/css/custom.css

2. CSS 적용

theme.properties에 다음 추가:

styles=css/custom.css

3. 로그인 템플릿에서 로고 사용 예시 

<img src="${url.resourcesPath}/img/logo.png" alt="Company Logo" height="80"/>

4. 색상, 버튼 스타일 커스터마이징 (custom.css 예시) 

body {
  background-color: #f4f6f9;
  font-family: 'Noto Sans KR', sans-serif;
}

.kc-login .btn-primary {
  background-color: #003366;
  border-color: #003366;
}

.kc-logo-text {
  color: #003366;
  font-weight: bold;
}

5. 전체 아키텍처 흐름 

[ 사용자 요청 ]
     ↓
[ Keycloak Theme Engine ]
     ↓
[ Freemarker Template + 사용자 테마 ]
     ↓
[ 렌더링된 HTML + CSS + JS ]
     ↓
[ 사용자에게 표시 ]

📸 시각화 예시:

+-------------------+
|  로그인 페이지     |
+-------------------+
|  [🚀회사로고]       |
|  사용자명 입력칸   |
|  비밀번호 입력칸   |
|  로그인 버튼      |
+-------------------+

🔚 요약

항목 설명
테마 종류 login, account, email, welcome
구조 themes/mytheme/ 하위에 템플릿 구성
템플릿 엔진 Apache Freemarker
주요 파일 login.ftl, theme.properties, custom.css
적용 방법 Realm 설정 또는 서버 환경변수
사용자 정의 가능 로고, 색상, 안내 문구, 이메일 등 전체 커스터마이징 가능

🎁 팁: docker-compose 환경에서 테마 테스트할 경우, volumes로 테마 디렉터리를 /opt/keycloak/themes에 mount하면 됩니다.

RSS Feed
마지막 수정일자
Keycloak과 OAuth2 / OIDCKeycloak과 어플리케이션 통합