Belajar Keycloak - SCIM User Provisioning | Belajar SSO dengan Keycloak

#Pendahuluan

Di episode 16 kalian membuka social login lewat identity brokering dan menghubungkan akun eksternal ke identitas internal. Episode 17 ini melengkapi siklus hidup identitas dari sisi yang lain: provisioning. Kalian akan belajar SCIM 2.0 — protokol REST untuk membuat, mengubah, dan menghapus user serta group lintas sistem secara otomatis — supaya onboarding karyawan baru tidak lagi berupa pekerjaan manual, melainkan aliran data yang konsisten dari sistem HR sampai Keycloak.

#Sekilas SCIM 2.0

SCIM (System for Cross-domain Identity Management) 2.0 adalah spesifikasi yang menstandarkan cara sistem identitas bertukar data user. Peran utamanya tiga:

REST API untuk manajemen user — sumber data (SCIM server) diekspos lewat HTTP, dan SCIM client memanggilnya untuk membaca dan mengubah resource.
Automatic provisioning dan deprovisioning — user dibuat, diperbarui, dan dinonaktifkan secara otomatis tanpa campur tangan admin.
Cross-system synchronization — satu perubahan di sistem sumber (misal HR) menjalar ke semua sistem target yang terhubung.

Satu prinsip penting: provisioning berbeda dari autentikasi. SCIM mengurus siapa yang ada di sistem; autentikasi mengurus siapa yang masuk. Keduanya bekerja berdampingan — SCIM memastikan user baru sudah ada di Keycloak sebelum user tersebut mencoba login.

#Operasi Dasar SCIM

SCIM memodelkan resource utama sebagai User dan Group, masing-masing dengan endpoint sendiri:

Operasi	Metode dan endpoint	Fungsi
Create	POST /Users	Membuat user baru
Read	GET /Users lalu identifier user	Mengambil data satu user
Update	PUT atau PATCH /Users lalu identifier user	Mengganti seluruh atau sebagian atribut
Delete	DELETE /Users lalu identifier user	Menghapus atau menonaktifkan user
Search	GET /Users dengan parameter filter	Mencari user sesuai kriteria
Groups	CRUD pada /Groups	Mengelola group dan keanggotaan

Contoh pemanggilannya lewat curl:

Operasi dasar SCIM 2.0

curl -X POST https://scim.example.com/v2/Users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
       "userName":"budi","active":true,
       "emails":[{"value":"budi@example.com","primary":true}]}'
 
curl -X PATCH https://scim.example.com/v2/Users/7f3c9a2d \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
       "Operations":[{"op":"replace","path":"active","value":false}]}'

POST /Users membuat user; PATCH dengan op bernilai replace bisa langsung mematikan akun dengan mengganti active menjadi false — ini pola deprovisioning yang umum. Setiap resource membawa skema urn:ietf:params:scim:schemas:core:2.0:User yang menandai struktur standarnya.

#Filter dan Pencarian

SCIM menyediakan pencarian terstruktur lewat parameter filter. Contohnya GET /Users dengan filter filter=userName eq "budi" atau filter=active eq false. Ini yang dipakai sinkronisasi untuk menemukan perbedaan antara dua sistem.

#SCIM di Keycloak

Dukungan SCIM di Keycloak datang lewat ekstensi — bukan fitur bawaan instalasi standar. Kalian menambahkan ekstensi SCIM sebagai modul ke server Keycloak:

Langkah mengaktifkan SCIM di Keycloak

1. Unduh ekstensi SCIM yang sesuai dengan versi Keycloak
2. Taruh file JAR ekstensi ke direktori providers Keycloak
3. Restart server Keycloak
4. Daftarkan kredensial SCIM di konfigurasi (token atau OAuth2)
5. Temukan endpoint SCIM yang diekspos untuk realm kalian
6. Uji dengan client provisioning seperti Okta atau Azure AD

#Endpoint dan Autentikasi

Setelah ekstensi aktif, Keycloak mengekspos endpoint SCIM per realm yang bisa menerima panggilan dari sistem lain. Autentikasinya memakai OAuth2 — sistem pengirim (SCIM client) mendapat token lewat client credentials, lalu memakainya pada setiap panggilan SCIM. Ini konsisten dengan pola machine-to-machine yang kalian pelajari di episode 6.

Authorization: Bearer pada header membawa token tersebut. Jangan pernah mengirim token di URL — ia bisa bocor lewat log dan riwayat server.

#Attribute Mapping

Skema SCIM dan model user Keycloak tidak selalu identik. Ekstensi menyediakan pemetaan atribut: misalnya userName SCIM ke username Keycloak, emails ke atribut email, dan active ke status enabled. Mapping yang benar di sini menentukan apakah user dari HR system sampai ke Keycloak dengan data yang utuh.

Tip

Mulailah dengan operasi baca dan pencarian: pastikan kalian bisa GET /Users dan memfilter user dari sistem lain sebelum menyalakan provisioning otomatis. Verifikasi baca dulu, baru tulis.

#Contoh Integrasi

Beberapa pola integrasi yang umum di lapangan:

Okta ke Keycloak — Okta bertindak sebagai sumber user (SCIM server) atau sebagai client yang memprovisioning user ke Keycloak, menyingkronkan perubahan akun secara berkala.
Azure AD ke Keycloak — user dari Microsoft Entra diprovisioning ke Keycloak, termasuk status enabled dan group keanggotaan.
HR system integration — sistem seperti Workday atau BambooHR menjadi sumber kebenaran; karyawan baru otomatis dibuat di Keycloak, dan yang berhenti otomatis dinonaktifkan.
Automated onboarding dan offboarding — alur penuh: kontrak masuk menciptakan akun dan group; kontrak berakhir menonaktifkan akun dan mencabut akses.

#Praktik Terbaik SCIM

Meski SCIM menyederhanakan provisioning, beberapa disiplin menjaga sistem tetap sehat:

Idempotent operations — memanggil operasi yang sama dua kali menghasilkan kondisi yang sama. PATCH yang mengatur active ke false dua kali tidak boleh menimbulkan error; ini membuat retry aman.
Error handling — periksa kode status dan pesan error, lalu bedakan error sementara (retry) dan permanen (butuh campur tangan manusia).
Rate limiting — batasi kecepatan panggilan agar sinkronisasi massal tidak membanjiri server target.
Webhook notifications — untuk reaksi langsung, sistem sumber mengirim pemberitahuan perubahan alih-alih menunggu sinkronisasi berkala.

Important

Jangan pernah menghapus user secara permanen saat deprovisioning. Nonaktifkan (set active menjadi false) lebih dulu — menghapus data identitas menghancurkan jejak audit dan membuat akun lama tidak bisa ditelusuri kembali.

#Penutup

Pada episode 17 ini, kalian mengotomatiskan provisioning user dengan SCIM 2.0: memahami peran SCIM sebagai REST API untuk manajemen identitas; menguasai operasi create, read, update, delete, dan search untuk user serta group; mengaktifkan ekstensi SCIM di Keycloak dengan autentikasi OAuth2; melihat pola integrasi dengan Okta, Azure AD, dan sistem HR; serta menerapkan praktik idempotensi, error handling, rate limiting, dan webhook.

Inti yang harus dibawa pulang:

SCIM mengurus lifecycle identitas, bukan autentikasi — keduanya bekerja berdampingan.
User, Group, dan filter adalah inti protokol — hampir semua integrasi dibangun di atasnya.
Dukungan SCIM di Keycloak lewat ekstensi dengan autentikasi token OAuth2.
Deprovisioning berarti menonaktifkan, bukan menghapus — jaga jejak audit tetap utuh.

Di episode 18 berikutnya, kita masuk ke pengendalian akses itu sendiri: groups dan roles — membuat hierarki group, realm roles dan client roles, composite roles, serta menerapkan RBAC dan ABAC di aplikasi.