Belajar Keycloak - OIDC Claims & User Profile

#Pendahuluan

Di episode 9 kalian melihat ID token berisi klaim seperti name dan email. Episode 10 ini membuka kap mesin: dari mana klaim itu berasal, klaim standar apa saja yang ada, bagaimana menambahkan klaim kustom lewat user attributes dan protocol mappers, serta bagaimana memilih strategi — muat semua di token, atau ambil dari UserInfo endpoint.

#Klaim Standar OIDC

OIDC mendefinisikan serangkaian klaim standar yang dibagi per kelompok:

• Profile claims — name, given_name, family_name, picture, dan lainnya.
• Email claims — email dan email_verified.
• Address claims — address yang berisi formatted, street_address, locality, region, postal_code, dan country.
• Phone claims — phone_number dan phone_number_verified.

Klaim-klaim ini dipetakan dari data user Keycloak oleh protocol mapper bawaan yang sudah menempel pada client scope profile, email, address, dan phone.

#Dari Atribut User Menjadi Klaim

Data user di Keycloak tersimpan dalam dua lapis:

• Atribut bawaan — field standar seperti nama depan, nama belakang, dan email.
• User attributes — field kustom yang dibuat admin, misalnya department atau employee_id.

Atribut kustom ditambahkan di halaman user, lalu diangkat menjadi klaim lewat mapper:

1. Buat user attribute di tab Attributes pada halaman user.
2. Buat protocol mapper tipe User Attribute di client scope atau client.
3. Set nama mapper, nama klaim, dan token mana yang memuatnya.

{
  "sub": "9c4d5e6f-...",
  "preferred_username": "budi",
  "department": "engineering",
  "employee_id": "EMP-1042"
}

Di atas, department dan employee_id adalah klaim kustom hasil mapping atribut user. Klaim ini kemudian bisa dibaca aplikasi untuk logika bisnis — misalnya menentukan menu yang muncul.

#Protocol Mappers

Protocol mapper adalah jembatan antara data Keycloak dan token. Keycloak menyediakan beberapa jenis mapper:

Mapper bisa ditempel di client scope (berlaku untuk semua client yang memakai scope itu) atau langsung di client (khusus client tersebut). Pilih client scope bila banyak client butuh klaim yang sama.

#Hardcoded Claims dan JavaScript Mappers

Dua mapper yang sering diabaikan padahal praktis:

• Hardcoded claim — menyisipkan nilai konstan tanpa membaca data user. Cocok untuk menandai versi atau environment, misalnya "tier": "gold" untuk semua token dari satu client.
• JavaScript mapper — menjalankan skrip kecil untuk mengubah satu atau lebih atribut menjadi satu klaim. Contoh: menggabungkan firstName dan lastName menjadi display_name, atau mengubah format nomor.

const fullName = user.getFirstName() + " " + user.getLastName();
token.setClaim("display_name", fullName);

Gunakan JavaScript mapper dengan hati-hati dan hanya bila mapper bawaan tidak mencukupi — skrip yang salah bisa melambatkan token issuance atau memunculkan bug yang sulit dilacak.

#Claims Mapping

Mapping klaim bukan hanya soal atribut. Empat pola mapping yang sering dipakai di produksi:

• Client scope mappers — menempelkan klaim pada scope sehingga berlaku untuk banyak client sekaligus.
• Audience mapper — menambahkan nilai aud sehingga token bisa dipakai di lebih dari satu resource server, atau justru mempersempit audiens.
• Role mapper — mengontrol bagaimana role (realm dan client) direpresentasikan dalam token.
• Group mapper — memetakan keanggotaan grup user ke klaim, berguna untuk atribusi organisasi.

#ID Token vs Access Token vs UserInfo

Tiga jalur klaim yang berbeda, dengan konsekuensi berbeda pula:

Untuk membaca profil lewat UserInfo, aplikasi cukup memanggil endpoint-nya dengan access token:

curl -s -H "Authorization: Bearer eyJhbGciOi..." \
  "https://kc.example.com/realms/my-realm/protocol/openid-connect/userinfo"

protocol/openid-connect/userinfo mengembalikan klaim yang diizinkan oleh scope yang disetujui user — kebalikan dari ID token yang isinya sudah terkunci sejak token diterbitkan.

#Strategi Klaim

Memilih di mana klaim ditempatkan adalah keputusan desain dengan tiga pertimbangan:

• ID token vs UserInfo — simpan klaim yang dibutuhkan saat render halaman pertama di ID token; tarik data tambahan dari UserInfo endpoint hanya saat dibutuhkan.
• Performance — setiap klaim memperbesar token, dan access token dikirim pada setiap request API. Jangan muat data yang tidak dipakai di setiap panggilan.
• Privacy — hindari memasukkan data sensitif seperti nomor KTP atau detail medis ke dalam token. Token bisa terlihat di log dan disimpan di berbagai lapisan; sedapat mungkin jaga token tetap ramping.

Ukuran juga biaya: token yang membengkak memperlambat request dan memboroskan memori. Aturan praktisnya, muat ke token hanya yang benar-benar dipakai setiap request; sisanya lewat UserInfo endpoint.

#Penutup

Episode 10 membahas klaim OIDC dan user profile: klaim standar dari profil hingga telepon, user attributes sebagai sumber data kustom, jenis-jenis protocol mappers termasuk hardcoded dan JavaScript mapper, pola claims mapping, serta strategi menyeimbangkan ID token, access token, dan UserInfo endpoint.

Inti yang harus dibawa pulang:

• Klaim berawal dari data, diangkat oleh mapper — user attributes menjadi klaim lewat protocol mappers.
• Token harus ramping — muat yang esensial saja, tarik sisanya dari UserInfo.
• Token tidak bisa ditarik — jangan simpan keputusan yang berubah di dalam token.
• Mapper client scope menang untuk pemakaian ulang — satu scope, banyak client.

Di episode 11 berikutnya kalian akan belajar session management — bagaimana Keycloak melacak sesi login di banyak aplikasi sekaligus, bagaimana single logout bekerja, dan bagaimana memantau serta mencabut sesi dari admin console.