Belajar Keycloak - User Federation | Belajar SSO dengan Keycloak

#Pendahuluan

Di episode 14 kalian menyambungkan aplikasi sebagai SAML service provider dan memastikan alur login berjalan mulus. Episode 15 ini berbalik ke belakang layar: dari mana sebenarnya identitas user berasal? Kalian akan belajar user federation — cara Keycloak membaca user dari penyimpanan eksternal seperti LDAP dan Active Directory tanpa menduplikasi data di setiap sistem. Di sinilah Keycloak berubah dari sekadar portal login menjadi jantung manajemen identitas perusahaan.

#Konsep User Federation

User federation adalah kemampuan Keycloak untuk memakai sumber identitas eksternal sebagai basis user-nya. Empat gagasan inti yang perlu kalian pegang:

External user stores — direktori user yang sudah ada, misalnya OpenLDAP, Active Directory, atau database aplikasi legacy.
Just-in-time provisioning — user dibuat di Keycloak secara otomatis saat pertama kali berhasil login, dari data penyimpanan eksternal.
User synchronization — data dari eksternal disalin ke Keycloak secara berkala agar berita grup, departemen, atau status aktif selalu segar.
Identity brokering — pola yang berbeda tapi terkait: user tetap di luar (misal di Google), dan Keycloak hanya mengalihkan autentikasi lewat broker (dibahas di episode 16).

Pembeda kuncinya: federation berarti Keycloak sendiri yang membaca user dari direktori eksternal; brokering berarti autentikasi diarahkan ke sistem lain yang memegang kredensial.

#LDAP User Federation

LDAP adalah protokol direktori paling umum di enterprise, dan provider LDAP adalah federation yang paling sering dipakai di Keycloak. Kalian menambahkannya lewat User Federation di admin console, memilih provider ldap. Konfigurasi khasnya seperti ini:

Pengaturan LDAP user federation

enabled: true
provider_id: ldap
vendor: other
connection_url: ldap://openldap:389
bind_dn: cn=admin,dc=example,dc=com
bind_credential: admin-password
users_dn: ou=users,dc=example,dc=com
edit_mode: READ_ONLY
username_ldap_attribute: uid
rdn_ldap_attribute: uid
uuid_ldap_attribute: entryUUID
user_object_classes: inetOrgPerson, organizationalPerson, person
import_enabled: true
sync_registrations: true

ldap://openldap:389 adalah connection URL ke server LDAP; port 389 untuk LDAP biasa, 636 untuk LDAPS yang terenkripsi. bind_dn adalah akun yang dipakai Keycloak untuk membaca direktori — sebaiknya akun baca-saja khusus, bukan admin direktori.

#Kunci yang Wajib Diisi

Connection URL — alamat server LDAP beserta portnya.
Bind DN dan kredensial — akun yang dipakai Keycloak untuk koneksi.
Users DN — cabang direktori tempat user berada, misalnya ou=users.
User object classes — kelas yang menandai entri sebagai user; inetOrgPerson adalah yang paling umum.
Attribut pemetaan — username_ldap_attribute, rdn_ldap_attribute, dan uuid_ldap_attribute menghubungkan entri LDAP dengan model user Keycloak.

#Read Only vs Write-through

LDAP provider punya mode penulisan yang menentukan apa yang terjadi ketika user diubah lewat Keycloak:

Mode	Perilaku	Kapan dipakai
Read Only	Keycloak hanya membaca; perubahan user ditolak atau hanya berlaku di Keycloak	Direktori dipegang sistem lain
Write-through	Perubahan user langsung ditulis balik ke LDAP	Keycloak menjadi titik kelola utama
Unsynced	Data LDAP disalin penuh dan dipegang Keycloak	Migrasi ke Keycloak penuh

Read Only adalah pilihan paling aman: kalian tidak pernah berisiko merusak direktori yang dirawat sistem lain. Write-through hanya masuk akal bila tim kalian memegang kendali penuh atas direktori.

#Import User dan Sinkronisasi

Dengan import_enabled, user yang berhasil login otomatis dibuat salinannya di database Keycloak. Keycloak juga menjalankan sinkronisasi berkala (scheduled sync) untuk menyamakan data, dan memungkinkan sinkronisasi manual kapan saja. Atribut user di Keycloak bisa di-set untuk dibaca dari LDAP pada login, sehingga perubahan di direktori langsung terlihat.

Warning

Mode Read Only dan import user yang diaktifkan bersama bisa menimbulkan kebingungan: password tetap divalidasi di LDAP, tetapi profil user disimpan di Keycloak. Dokumentasikan dengan jelas ke mana perubahan profil harus ditulis agar tim tidak saling menimpa data.

#Active Directory dan Kerberos

Active Directory pada dasarnya adalah LDAP dengan skema Microsoft. Untuk integrasi AD, vendor dipilih sebagai Active Directory sehingga pemetaan atribut (seperti sAMAccountName dan objectGUID) menyesuaikan otomatis. Sinkronisasi group juga berjalan: group AD bisa dipetakan ke group Keycloak, lalu diwariskan ke user yang diimport.

Untuk lingkungan yang sudah berbasis Kerberos, Keycloak menyediakan provider Kerberos yang memungkinkan login tanpa password di host yang terdaftar — mirip konsep cross-realm yang kalian pelajari di series Kerberos. Ini dipakai untuk integrasi dengan Active Directory yang ter-hubung Keycloak realm, dan umumnya dipasangkan dengan protocol mapper yang membaca principal dari token.

#Custom User Storage

Tidak semua penyimpanan user berbentuk LDAP. Keycloak menyediakan User Storage SPI (Service Provider Interface) yang membiarkan kalian menulis provider sendiri untuk sumber data apa pun:

Database user provider — membaca user dari database relasional aplikasi yang sudah ada.
REST API user provider — memanggil API eksternal untuk mencari dan memvalidasi user.
Legacy system integration — menggabungkan sistem lama yang tidak berbicara LDAP maupun OIDC.

Provider kustom mengimplementasikan antarmuka seperti UserLookupProvider, UserQueryProvider, dan CredentialInputValidator. Karena ini kode Java yang di-deploy sebagai modul, penulisannya butuh pemahaman framework dan pengujian menyeluruh sebelum dipakai production.

#User Import Massal

Untuk penyimpanan yang sepenuhnya dipindahkan ke Keycloak, kalian mengimpor user dalam skala besar:

Bulk user import — memakai Admin REST API dengan loop untuk membuat banyak user sekaligus.
CSV import — membaca file CSV kolom per kolom dan memetakannya ke atribut user.
Migration strategies — menentukan urutan pindah: impor user dulu, lalu reset password, lalu aktifkan federation.
Data transformation — membersihkan dan menstandarkan data lama sebelum masuk, misalnya menormalisasi format email atau menggabungkan nama terpisah.

Import user massal via Admin REST API

TOKEN=$(curl -s -d "client_id=admin-cli&username=admin&password=admin&grant_type=password" \
  http://localhost:8080/realms/master/protocol/openid-connect/token | jq -r .access_token)
 
while IFS="," read -r user email; do
  curl -s -X POST http://localhost:8080/admin/realms/demo/users \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"username\":\"$user\",\"email\":\"$email\",\"enabled\":true}"
done < users.csv

grant_type=password dengan client admin-cli adalah cara ringkas mengambil token admin. Perhatikan juga: jangan pernah menulis password plaintext di file CSV; set password sementara lalu wajibkan reset pada login pertama.

#Penutup

Pada episode 15 ini, kalian menghubungkan Keycloak dengan penyimpanan user eksternal: konsep federation, just-in-time provisioning dan sinkronisasi; konfigurasi LDAP dengan connection URL, bind DN, dan object class; perbedaan Read Only dan Write-through; integrasi Active Directory dan Kerberos; custom user storage lewat SPI; serta strategi import user massal.

Inti yang harus dibawa pulang:

Federation membaca user dari direktori eksternal tanpa menduplikasi kelola identitas.
Read Only adalah pilihan paling aman untuk direktori yang dirawat sistem lain.
Import user menyalin data ke Keycloak, cocok untuk migrasi penuh, bukan untuk direktori hidup.
Custom SPI ada untuk sumber data yang bukan LDAP maupun database standar.

Di episode 16 berikutnya, kita menambahkan pintu masuk lain: social login dan identity brokering — membiarkan user masuk dengan akun Google, GitHub, atau Facebook, dan menghubungkannya ke identitas internal lewat first broker login.