Themes

Keycloak theme คืออะไร?

Keycloak แสดงผลหน้าต่างๆ โดยใช้ HTML template ของตัวเอง แต่ละหมวดหมู่ของหน้าเรียกว่า theme type:

Theme type	สิ่งที่ควบคุม
`login`	หน้า login, ลงทะเบียน, รีเซ็ตรหัสผ่าน และ OTP
`account`	Account management console แบบ self-service
`email`	Email template (verification, password reset ฯลฯ)
`admin`	Keycloak admin console เอง

login theme คือสิ่งที่ end-user ของคุณเห็น การปรับแต่งให้ตรงกับแบรนด์ของคุณทำให้ประสบการณ์การ authenticate รู้สึกเป็นส่วนหนึ่งของผลิตภัณฑ์

คุณสามารถเปลี่ยน login theme ที่ใช้งานอยู่ของ realm ใดก็ได้จาก admin console:

เปิด admin console และเลือก realm ของคุณจาก drop-down ซ้ายบน
คลิก Realm settings ใน sidebar ซ้าย
คลิกแท็บ Themes
ใต้ Login theme เปิด drop-down และเลือก theme ของคุณ (เช่น keycloak สำหรับค่าเริ่มต้น หรือชื่อ custom theme ของคุณ)
ใต้ Account theme, Email theme และ Admin console theme เลือกตามต้องการ
คลิก Save

การเปลี่ยนแปลงมีผลทันที ไม่จำเป็นต้องรีสตาร์ท

โครงสร้างของ custom theme

custom theme คือโฟลเดอร์ที่คุณวางไว้ใต้โฟลเดอร์ themes/ ของ Keycloak โครงสร้างขั้นต่ำสำหรับ login theme มีลักษณะดังนี้:

flowchart TD
  T["themes/"] --> B["my-brand/"]
  B --> L["login/"]
  L --> P["theme.properties"]
  L --> R["resources/"]
  R --> CSS["css/login.css"]
  R --> IMG["img/logo.png"]
  L --> M["messages/messages_en.properties"]

A custom theme's directory structure

ไฟล์ theme.properties ประกาศว่า theme ของคุณสืบทอดจาก parent theme ใด เริ่มต้นด้วยการขยาย theme keycloak ที่มีอยู่แล้ว เพื่อให้คุณต้อง override เฉพาะสิ่งที่เปลี่ยนแปลงเท่านั้น:

parent=keycloak
import=common/keycloak

ด้วยการตั้งค่านี้ Keycloak จะ fallback ไปยัง parent สำหรับ template หรือ resource ใดที่คุณยังไม่ได้ override

การ deploy custom theme

สำหรับ Keycloak รุ่น Quarkus ให้คัดลอกโฟลเดอร์ theme ของคุณไปยัง /opt/keycloak/themes/ ของ container วิธีง่ายที่สุดด้วย Docker คือการใช้ bind-mount:

docker run -p 8080:8080 \
  -v "$(pwd)/themes/my-brand:/opt/keycloak/themes/my-brand" \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest \
  start-dev

หลังจาก container เริ่มต้น theme ของคุณจะปรากฏใน drop-down Login theme ใน Realm settings

Keycloakify สำหรับ React-based theme

หากคุณต้องการสร้างหน้า login ด้วย React Keycloakify (keycloakify.dev) คือ tool ที่แนะนำ Keycloakify จะคอมไพล์ React component ของคุณเป็น Keycloak-compatible theme JAR ผลลัพธ์เป็นไฟล์ .jar ที่คุณวางไว้ใน /opt/keycloak/providers/ — Keycloak จะ auto-discover ให้ตอน startup

Keycloakify ให้คุณควบคุม React component แบบ full สำหรับทุกหน้า login โดยยังคงเข้ากันได้กับ protocol การส่งข้อความและ form ภายในของ Keycloak

ข้อแลกเปลี่ยน

ตัวเลือก	Benefit	Cost
Custom theme สืบทอดจาก `keycloak` parent	override เฉพาะไฟล์ที่ต้องเปลี่ยน ได้ประโยชน์จาก fix และ feature ใหม่ของ parent theme โดยอัตโนมัติ	ต้องตรวจสอบทุกครั้งที่อัปเกรด Keycloak ว่า template ที่ override ไว้ยังเข้ากันได้กับ parent เวอร์ชันใหม่หรือไม่
Keycloakify (React-based theme)	ควบคุม UI แบบ full ด้วย React component ที่ทีม frontend คุ้นเคยอยู่แล้ว	เพิ่มขั้นตอน build เป็น JAR และต้องเรียนรู้จุดเชื่อมต่อกับ protocol ภายในของ Keycloak
แก้ไข built-in theme (`keycloak`) โดยตรง	เห็นผลเร็วเพราะไม่ต้องสร้างโครงสร้าง theme ใหม่	การอัปเกรด Keycloak จะเขียนทับไฟล์ built-in ทั้งหมด ทำให้การแก้ไขหายไปโดยไม่รู้ตัว

ข้อผิดพลาดที่พบบ่อย

แก้ไข built-in theme (keycloak) ไว้ในที่ตั้งเดิมโดยตรง — เมื่ออัปเกรด Keycloak เวอร์ชันใหม่ ไฟล์ built-in ทั้งหมดจะถูกเขียนทับ ทำให้การปรับแต่งหายไปโดยไม่มีการเตือน ควรสร้าง custom theme แยกที่สืบทอดจาก parent เสมอ
ไม่ทดสอบ custom theme กับ theme type อื่นนอกจาก login — ปรับแต่งเฉพาะหน้า login แต่ลืมว่า account, email และ admin theme ก็ควรได้รับการพิจารณาเรื่อง branding ด้วยเช่นกัน โดยเฉพาะ email template ที่ user เห็นบ่อยไม่แพ้หน้า login
Deploy custom theme แล้วไม่รีสตาร์ทหรือ clear cache ตอน dev — Keycloak cache theme resource ไว้ในโหมด production ทำให้การเปลี่ยนแปลงไม่ปรากฏจนกว่าจะรีสตาร์ทหรือปิด theme cache ระหว่างพัฒนา

💡 ตัวอย่างจากของจริง

Keycloakify ในโปรดักชัน — ทีม frontend จำนวนมากใช้ Keycloakify เพื่อ compile React component ชุดเดียวกับที่ใช้ในแอปหลัก ให้กลายเป็นหน้า login ของ Keycloak ทำให้ประสบการณ์ผู้ใช้ต่อเนื่องเป็นแบรนด์เดียวกันตั้งแต่หน้า login ไปจนถึงตัวแอป

Enterprise white-labeling — บริษัทที่ให้บริการ platform แบบ multi-tenant มักสร้าง custom theme แยกต่อ realm เพื่อให้แต่ละลูกค้าเห็นหน้า login ที่มี logo และสีของแบรนด์ตัวเอง ทั้งที่ใช้ Keycloak instance เดียวกันเบื้องหลัง