Belajar Keycloak - OAuth 2.0 Scopes & Consent

#Pendahuluan

Di episode 7 kalian mengelola token: refresh, rotasi, dan revoke. Episode 8 ini menjawab pertanyaan yang lebih mendasar: data apa yang boleh diambil aplikasi dari akun user, dan siapa yang memutuskan? Jawabannya ada di dua mekanisme OAuth 2.0 yang saling berkaitan — scope untuk membatasi permintaan, dan consent untuk persetujuan user.

#Apa Itu Scope

Scope adalah label permintaan izin yang dikirim aplikasi saat meminta token. Saat aplikasi meminta profile, dia sedang berkata: "saya butuh data profil user". Keycloak lalu memetakan scope itu ke serangkaian claims lewat protocol mappers.

Di Keycloak, scope tidak dideklarasikan sendiri-sendiri di dalam client, melainkan dibungkus sebagai client scope — kumpulan mapper yang bisa dipakai ulang oleh banyak client. Klien cukup menunjuk client scope mana yang dibutuhkan.

#Scope Standar OIDC

Beberapa scope sudah tersedia bawaan di realm:

• openid — menandakan request OIDC, memicu penerbitan ID token.
• profile — claims profil seperti name, given_name, dan family_name.
• email — claims email dan email_verified.
• offline_access — mengizinkan offline refresh token seperti di episode 7.

curl -X POST "https://kc.example.com/realms/my-realm/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=my-app" \
  -d "client_secret=4f9a2c8d..." \
  -d "code=1c2a3b..." \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email"

scope=openid profile email di atas meminta tiga scope sekaligus. Perhatikan bahwa openid selalu wajib untuk alur OIDC — tanpanya, Keycloak tidak mengeluarkan ID token.

#Scope Kustom dan Dynamic Scopes

Selain scope bawaan, kalian bisa membuat client scope sendiri:

1. Buka menu Client scopes di admin console, lalu Create client scope.
2. Beri nama, misalnya user-details, dan pilih tipe Optional.
3. Tambahkan protocol mapper ke dalamnya — misalnya mapper untuk atribut user tertentu.
4. Lampirkan client scope itu ke client di tab Client scopes.

Hasilnya bisa terlihat di payload token:

{
  "scope": "openid profile email user-details",
  "preferred_username": "budi",
  "department": "engineering"
}

Keycloak juga mendukung dynamic scopes — scope yang membawa nilai dinamis, seperti number_format:ID atau language:ja, yang memicu mapper khusus di realm. Fitur ini diaktifkan di Realm settings, cocok untuk layanan yang butuh parameterisasi scope seperti pencetakan dokumen atau terjemahan.

#Scope vs Role

Scope dan role sering tertukar. Keduanya memang sama-sama label, tetapi posisinya berbeda:

Analoginya: scope adalah izin melihat dokumen, role adalah izin menandatangani dokumen. Aplikasi perlu keduanya bekerja bersama.

#Client Scopes: Default vs Optional

Saat mengatur client, tab Client scopes memiliki dua kategori lampiran:

• Default — otomatis disertakan setiap kali client meminta token, tanpa perlu dipanggil eksplisit di parameter scope.
• Optional — hanya disertakan bila client menyebutkan nama scope-nya di parameter scope.

Pola umum: masukkan openid, profile, dan email sebagai default, dan jadikan scope dengan data sensitif sebagai optional. Dengan begitu client yang tidak butuh data itu tidak akan mendapatkannya secara diam-diam.

#Layar Consent

Ketika client mencentang Consent required, Keycloak menampilkan layar consent setelah login berhasil. Di layar itu user melihat daftar izin yang diminta — misalnya "Lihat email Anda" dan "Lihat profil Anda" — dan memilih Yes atau No. Ini adalah momen di mana user memegang kendali atas datanya sendiri.

Alur consent hanya berjalan satu kali per user dan client selama pemberian masih berlaku. Setelah user menyetujui, request berikutnya dianggap sudah diauthorized — Keycloak menyebut client itu sebagai pre-authorized untuk user tersebut. Jika kalian ingin konsistensi UI tertentu atau client internal yang dipercaya penuh, ada pengaturan untuk melewati layar consent sepenuhnya.

#Mengelola Consent User

Consent bukan keputusan sekali dan selamanya. User bisa mencabutnya kapan saja:

• Melalui account console — user membuka menu Signing in lalu Manage consent grants dan mencabut aplikasi yang tidak diinginkan lagi.
• Melalui admin — admin bisa menghapus consent grant dari halaman user di admin console.
• Melalui layar login — Keycloak menampilkan kembali layar consent untuk izin yang belum pernah disetujui sebelumnya.

Setelah consent dicabut, client harus meminta izin ulang pada kunjungan berikutnya — efek yang sama dengan logout, tetapi khusus untuk lingkup data.

#Penegakan Scope

Scope hanya berguna jika ditegakkan. Di sisi Keycloak dan aplikasi:

• Konfigurasi client scope — pastikan client scope yang sensitif tidak masuk ke daftar default tanpa kebutuhan.
• Optional vs default — data yang tidak wajib dijadikan optional agar user diberi kesempatan memilih.
• Audience restrictions — batasi aud token ke client yang tepat lewat Audience mapper, sehingga token tidak dipakai lintas aplikasi di luar peruntukannya.
• Fine-grained permissions — untuk kontrol akses yang lebih detail, gunakan fitur authorization services Keycloak di atas role dan scope.

#Praktik Terbaik

Empat kebiasaan yang menjaga scope tetap sehat di produksi:

• Prinsip least privilege — beri client sesedikit mungkin: scope yang tidak dibutuhkan jangan diminta.
• Deskripsi scope yang jelas — tulis deskripsi setiap client scope agar tampil informatif di layar consent.
• Layar consent yang ramah user — nama client yang dikenali dan teks yang membangun kepercayaan.
• Dokumentasi scope — catat scope apa yang dimiliki setiap client dan mengapa; ini mempermudah audit.

#Penutup

Di episode 8 ini kalian memahami scopes dan consent: definisi scope dan client scope, scope standar OIDC, scope kustom dan dynamic scopes, perbedaan scope dengan role, client scopes default vs optional, alur layar consent, pengelolaan consent oleh user dan admin, serta penegakan dan praktik terbaiknya.

Inti yang harus dibawa pulang:

• Scope menjawab "data apa", role menjawab "aksi apa" — keduanya berjalan berdampingan.
• Default scope harus hemat — jadikan data sensitif optional agar user diberi pilihan.
• Consent adalah kendali user — hormati dan buat layarnya mudah dipahami.
• Least privilege adalah standar — client minta sedikit mungkin, bukan semaunya.

Di episode 9 berikutnya kita naik ke lapisan di atas OAuth 2.0: OpenID Connect — protokol yang mengubah otorisasi murni menjadi autentikasi terstandar dengan ID token dan discovery mechanism.