Konfigurasi SSO Custom Domain
Panduan admin mendaftarkan custom domain pada Keycloak — menambahkan Valid Redirect URI, Web Origin di client, serta Content-Security-Policy di Realm Settings.
Ketika sebuah workspace mendaftarkan Custom Domain, domain baru tersebut harus didaftarkan pada Keycloak agar login (SSO) berjalan. Tanpa langkah ini, akses ke domain baru akan gagal dengan error Invalid parameter: redirect_uri, permintaan CORS ditolak, atau halaman gagal dimuat karena diblokir kebijakan keamanan browser.
Panduan ini ditujukan untuk administrator yang memiliki akses ke Keycloak Admin Console. Untuk langkah pendaftaran custom domain dari sisi Studio, lihat Custom Domain.
Login Keycloak dan Memilih Realm
- Buka Keycloak Admin Console dan login menggunakan akun Admin.
- Klik dropdown Realm di kiri atas, lalu pilih realm yang digunakan aplikasi (contoh:
alurkerja).
Menambahkan Valid Redirect URI dan Web Origin ke Client
-
Buka Client Pada sidebar, klik menu Clients, pilih client yang digunakan aplikasi, lalu buka tab Settings.
-
Tambahkan Valid Redirect URI Pada bagian Valid redirect URIs, klik Add lalu masukkan custom domain diikuti pola
/*(misalnyahttps://app.namadomain.com/*) agar seluruh path pada domain tersebut diizinkan sebagai tujuan redirect setelah login.
-
Tambahkan Web Origin Pada bagian Web origins, klik Add lalu masukkan custom domain tanpa pola
/*(misalnyahttps://app.namadomain.com) agar permintaan CORS dari domain tersebut diizinkan.
-
Simpan Klik Save di bagian bawah halaman agar perubahan diterapkan.
Perhatikan perbedaan formatnya: Valid redirect URIs memakai pola /* di akhir (contoh https://app.namadomain.com/*), sedangkan Web origins ditulis tanpa path (contoh https://app.namadomain.com).
Menambahkan Custom Domain ke Content Security Policy
Selain di client, custom domain juga perlu ditambahkan pada Content-Security-Policy (CSP) di level realm agar aplikasi dapat ditampilkan (misalnya di dalam iframe) tanpa diblokir oleh browser.
-
Buka Realm Settings Pada sidebar Keycloak Admin Console, klik Realm settings.
-
Buka Tab Security Defenses Pilih tab Security defenses, lalu buka sub-tab Headers.
-
Tambahkan Domain pada Content-Security-Policy Pada kolom Content-Security-Policy, tambahkan custom domain ke direktif
frame-ancestors(dan direktif lain yang relevan sesuai kebutuhan). Anda dapat menuliskan domain spesifik (https://app.namadomain.com) maupun pola wildcard (https://*.namadomain.com). Klik Save untuk menyimpan.
Setelah menyimpan perubahan pada client maupun CSP, minta pengguna mengakses kembali custom domain. Jika halaman login sebelumnya sudah terbuka, muat ulang (refresh) browser agar konfigurasi terbaru terpakai.
Checklist
Untuk setiap custom domain baru, pastikan seluruh entri berikut sudah ditambahkan:
| Lokasi di Keycloak | Yang ditambahkan | Format |
|---|---|---|
| Client → Settings → Valid redirect URIs | Custom domain + /* | https://app.namadomain.com/* |
| Client → Settings → Web origins | Custom domain tanpa path | https://app.namadomain.com |
| Realm settings → Security defenses → Content-Security-Policy | Custom domain pada frame-ancestors | https://app.namadomain.com atau https://*.namadomain.com |