Belajar Keycloak - Tema & Kustomisasi
Mengubah tampilan Keycloak lewat tema: memahami lima jenis tema, struktur direktori tema dengan template FreeMarker dan message bundle, serta kustomisasi branding dan multi-bahasa.
#Pendahuluan
Di episode 20 kalian menyetel realm, client, dan alur autentikasi. Episode 21 ini tentang sisi yang langsung terlihat user: tema. Halaman login default Keycloak itu generik; dengan memahami struktur tema kalian bisa mengganti logo, warna, template email, bahkan menambah bahasa. Kustomisasi tema juga bagian dari profesionalisme layanan SSO — user menilai keamanan dari tampilan yang mereka percaya.
#Lima Jenis Tema
Keycloak punya lima jenis tema, masing-masing untuk permukaan yang berbeda:
| Jenis Tema | Dipakai untuk | Diatur di |
|---|---|---|
| Login | Halaman login, register, reset password | Realm Settings → Themes |
| Account | Halaman akun user (profil, sesi, password) | Realm Settings → Themes |
| Admin Console | Antarmuka administrator | Admin console |
| Template email (verify, reset password) | Realm Settings → Themes | |
| Welcome | Halaman selamat datang dan pembuatan admin awal | Pengaturan server |
Perhatikan bahwa tema admin console dan welcome diatur di level yang berbeda dari login/account/email — jangan heran jika mengubah tema login tidak mengubah admin console.
#Struktur Direktori Tema
Tema hidup di folder themes/ dengan satu subfolder per jenis. Contoh themes/mytema/login/ untuk tema login kustom. Berkas intinya:
| Isi | Keterangan |
|---|---|
theme.properties | Metadata tema: parent, styles, import |
*.ftl | Template FreeMarker untuk halaman |
styles.css | Styling halaman |
script.js | JavaScript tambahan |
resources/ | Gambar dan aset lain |
messages/ | Message bundle untuk terjemahan |
#theme.properties
Kunci terpenting adalah parent. Dengan parent=keycloak, tema kalian mewarisi template bawaan sehingga tidak perlu menulis ulang semuanya:
parent=keycloak
import=common/keycloak
styles=css/styles.cssSaat versi Keycloak naik, template bawaan yang diwarisi ikut terbarui — inilah alasan menetapkan parent daripada menyalin seluruh tema.
#Template FreeMarker
Halaman login ditulis sebagai template FreeMarker, seperti login.ftl, register.ftl, dan reset-password.ftl. Template adalah tempat kalian mengubah struktur HTML, bukan sekadar warna.
#Kustomisasi
#Branding (Logo dan Warna)
Mulai dari yang paling mudah: taruh logo di resources/, lalu deklarasikan di styles.css. Tanpa mengubah template, identitas visual langsung berubah di semua halaman turunan.
#Custom Login Pages
Untuk perubahan struktural, edit login.ftl atau template lain. Setelah selesai, pilih tema di Realm Settings → Themes dan uji pada halaman login realm.
#Custom Error Pages
Halaman error (misal sesi kedaluwarsa atau akses ditolak) juga punya template sendiri, seperti error.ftl. Sesuaikan agar pesan error tetap jelas tapi tidak membocorkan detail internal.
#Custom Email Templates
Tema email berisi template FreeMarker seperti password-reset.ftl dan email-verify.ftl. Inilah yang menentukan isi email reset password yang dibahas di episode 20 — penting untuk branding dan bahasa.
#Multi-Language Support
Terjemahan disimpan sebagai message bundle di messages/. Buat messages_id.properties untuk Bahasa Indonesia:
loginTitle=Masuk
loginAccountTitle=Masuk ke akun Anda
doLogin=MasukKeycloak memilih bundle berdasarkan locale browser user. Dengan cara ini kalian menambah bahasa tanpa menyentuh satu pun template.
#Advanced Customization
Ketika tema saja tidak cukup, Keycloak menyediakan SPI (Service Provider Interface) untuk perpanjangan kode Java:
- Custom authenticators — langkah autentikasi baru, misalnya OTP via SMS.
- Custom protocol mappers — menambah klaim khusus ke token.
- Custom user storage providers — membaca user dari sumber eksternal seperti LDAP atau database lama.
- Event listeners — menangkap event untuk integrasi (dibahas di episode 22).
Provider disimpan sebagai JAR di folder providers:
cp my-provider.jar keycloak/providers/
bin/kc.sh start-devSaat server dimulai, Keycloak otomatis memuat JAR dari folder tersebut. Uji provider di lingkungan terpisah sebelum menyentuh produksi.
#Penutup
Pada episode 21, kalian memahami tema Keycloak: lima jenis tema (login, account, admin console, email, welcome), struktur direktori (theme.properties, template FreeMarker, CSS, JavaScript, resources, message bundle), kustomisasi branding dan multi-bahasa, serta perpanjangan lanjutan lewat SPI.
Inti yang harus dibawa pulang:
- Selalu set
parent=keycloakagar tema mudah dirawat saat versi naik. - Message bundle
messages_id.propertiesmenghidupkan Bahasa Indonesia tanpa mengubah template. - Uji tema di realm staging sebelum dipakai di produksi.
- Custom SPI butuh JAR dan rebuild — kelola sebagai bagian dari pipeline, bukan copy-paste manual.
Di episode 22 berikutnya, kalian akan memanfaatkan jejak aktivitas: Events & Auditing — event types, event listeners, dan bagaimana merekam siapa masuk, siapa yang berbuat apa, serta kapan.