Belajar Keycloak - OpenID Connect Fundamentals

#Pendahuluan

Empat episode terakhir kalian bekerja dengan OAuth 2.0 murni: token, scopes, dan consent. Episode 9 ini membuka fase baru — OpenID Connect (OIDC). Kalau OAuth 2.0 menjawab pertanyaan "siapa yang boleh mengakses apa", OIDC menjawab pertanyaan yang lebih mendasar: "siapakah user ini, dan dari mana aplikasi tahu?" OIDC adalah jawaban standar yang dipakai Keycloak sebagai identity provider.

#OIDC: Lapisan Identitas di Atas OAuth 2.0

OIDC adalah identity layer yang dibangun di atas OAuth 2.0. Ia tidak menggantikan OAuth — ia menambahkan apa yang selama ini hilang:

• Standardized authentication — cara terstandar bagi aplikasi untuk membuktikan bahwa user memang user yang dia klaim.
• ID token — token JWT khusus yang membawa identitas user, hal yang tidak ada di OAuth 2.0 murni.
• UserInfo endpoint — endpoint terstandar untuk mengambil profil user.
• Discovery mechanism — metadata publik yang membuat integrasi lebih mudah.

Kunci di balik layar: access token dari OAuth 2.0 tetap ada, tetapi sekarang ada token kedua bernama ID token yang menjadi bukti autentikasi.

#Alur OIDC

OIDC mewarisi alur alur OAuth 2.0, dengan nuansa masing-masing:

• Authorization Code flow — alur yang direkomendasikan: kode ditukar di backend, ID token dan access token dikeluarkan lewat token endpoint. Ini satu-satunya alur yang dianjurkan untuk aplikasi baru, apalagi dengan PKCE.
• Implicit flow — alur lawas yang menyerahkan token langsung lewat redirect URI. Tidak direkomendasikan karena token terekspos di URL browser.
• Hybrid flow — kompromi: sebagian respons lewat authorization endpoint, sebagian lewat token endpoint. Dipakai untuk kasus khusus yang jarang.

Aturan praktis yang aman: pakai authorization code flow dengan PKCE. Dua alur lainnya hanya untuk kompatibilitas.

#ID Token dan Struktur JWT

ID token adalah JWT (JSON Web Token) — tiga bagian yang masing-masing di-encode base64url, dipisahkan titik:

• Header — algoritma tanda tangan dan id kunci (alg, kid).
• Payload — klaim identitas user.
• Signature — tanda tangan kriptografis dari Keycloak.

Contoh payload ID token:

{
  "exp": 1754213000,
  "iat": 1754212700,
  "auth_time": 1754212700,
  "jti": "a3f2c1d0-...",
  "iss": "https://kc.example.com/realms/my-realm",
  "aud": "my-app",
  "sub": "9c4d5e6f-...",
  "typ": "ID",
  "azp": "my-app",
  "nonce": "1a2b3c4d",
  "name": "Budi Santoso",
  "preferred_username": "budi",
  "email": "budi@example.com",
  "email_verified": true
}

Lihat typ bernilai ID — inilah penanda bahwa token ini memang ID token, bukan access token.

#Perbedaan ID Token dan Access Token

Kesalahan klasik: mengirim ID token sebagai Bearer token ke API. ID token bukanlah pengganti access token — resource server tidak seharusnya memercayai token yang audiensnya adalah aplikasi klien.

#Klaim Standar dan Klaim Kustom

OIDC mendefinisikan klaim standar yang wajib atau umum ada di ID token:

• sub — identifikasi user yang unik dan abadi di realm.
• iss — penerbit token, harus persis URL issuer realm.
• aud — audiens yang dituju, biasanya client id aplikasi.
• exp dan iat — waktu kedaluwarsa dan waktu diterbitkan.
• auth_time — kapan user terakhir melakukan autentikasi penuh.

Di atas klaim standar, Keycloak bisa menambahkan custom claims lewat protocol mappers — misalnya atribut user atau role. Ini akan dibahas dalam di episode 10.

#Memvalidasi ID Token

Menerima ID token tanpa validasi sama saja dengan membiarkan siapa pun masuk. Langkah wajibnya:

1. Pastikan iss persis cocok dengan URL issuer realm.
2. Pastikan aud berisi client id kalian.
3. Verifikasi signature JWT menggunakan kunci publik Keycloak dari JWKS endpoint.
4. Periksa exp belum lewat dan iat tidak masuk akal jauh ke masa depan.
5. Cocokkan nonce yang disimpan saat memulai request.

curl -s "https://kc.example.com/realms/my-realm/protocol/openid-connect/certs"

protocol/openid-connect/certs mengembalikan kunci publik dalam format JWK. Di sebagian besar framework, langkah validasi ini ditangani middleware — tetapi kalian wajib memahami apa yang diperiksa.

#UserInfo Endpoint

Selain klaim di dalam ID token, OIDC menyediakan UserInfo endpoint untuk mengambil profil user secara terpisah:

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

Respons berupa JSON berisi klaim yang diizinkan oleh scope yang disetujui. Karena diambil dengan access token, response UserInfo bisa lebih kaya daripada ID token — ini soal strategi klaim yang dibahas di episode 10.

#Discovery dan Metadata

OIDC membungkus semua alamat endpoint dalam satu file metadata publik:

curl -s "https://kc.example.com/realms/my-realm/.well-known/openid-configuration"

{
  "issuer": "https://kc.example.com/realms/my-realm",
  "authorization_endpoint": "https://kc.example.com/realms/my-realm/protocol/openid-connect/auth",
  "token_endpoint": "https://kc.example.com/realms/my-realm/protocol/openid-connect/token",
  "jwks_uri": "https://kc.example.com/realms/my-realm/protocol/openid-connect/certs",
  "userinfo_endpoint": "https://kc.example.com/realms/my-realm/protocol/openid-connect/userinfo",
  "end_session_endpoint": "https://kc.example.com/realms/my-realm/protocol/openid-connect/logout",
  "grant_types_supported": ["authorization_code", "client_credentials", "refresh_token"]
}

Dengan metadata ini, library OIDC apa pun bisa mengonfigurasi dirinya sendiri — cukup beri tahu URL issuer, sisanya ditemukan otomatis. /.well-known/openid-configuration adalah pintu masuk semua integrasi.

#Dynamic Client Registration

OIDC juga mendefinisikan dynamic client registration — client mendaftarkan dirinya sendiri ke Keycloak lewat request tanpa campur tangan admin. Keycloak mendukungnya di endpoint registrasi, tetapi fitur ini harus diaktifkan eksplisit di Realm settings karena membuka pintu pendaftaran otomatis. Untuk lingkungan produksi yang ketat, matikan saja dan daftarkan client secara manual.

#Penutup

Di episode 9 ini kalian mengenal OIDC: posisinya sebagai lapisan identitas di atas OAuth 2.0, alur-alur utamanya, struktur JWT ID token, klaim standar dan kustom, langkah validasi token, UserInfo endpoint, discovery metadata, dan dynamic client registration.

Inti yang harus dibawa pulang:

• OIDC menambahkan identitas di atas otorisasi — ID token adalah bukti autentikasi, bukan izin akses.
• ID token bukan access token — jangan pernah mengirimnya ke API tujuan.
• Validasi selalu wajib — cek iss, aud, exp, signature, dan nonce.
• Discovery membuat integrasi sederhana — cukup satu URL issuer, endpoint lain ditemukan otomatis.

Di episode 10 berikutnya kalian akan membedah klaim OIDC dan user profile — klaim standar apa saja yang tersedia, bagaimana menambahkan atribut kustom lewat protocol mappers, dan kapan sebaiknya memakai ID token atau UserInfo endpoint.