Belajar Keycloak - Authorization Code Flow

#Pendahuluan

Episode 4 memperkenalkan OAuth 2.0 secara umum dan menyebut Authorization Code sebagai grant type paling aman untuk web app. Episode 5 ini membedahnya langkah demi langkah: bagaimana browser, aplikasi, dan Keycloak berkomunikasi, apa yang terjadi saat pengguna login, bagaimana kode ditukar menjadi token, dan bagaimana PKCE membuat alur ini tetap aman untuk SPA dan aplikasi mobile.

#Mengapa Authorization Code Flow

Authorization Code adalah grant type paling aman untuk aplikasi web karena password pengguna tidak pernah sampai ke aplikasi atau browser — pengguna berinteraksi langsung dengan halaman login Keycloak. Aplikasi hanya menerima kode berumur pendek yang ditukar dengan token di server, sehingga access token tidak pernah terekspos di URL atau JavaScript.

Karena keamanan inilah flow ini menjadi standar de facto untuk web app modern dan menjadi dasar dari banyak integrasi SSO.

#Langkah-Langkah Alur

Authorization Code flow berjalan dalam enam langkah utama:

#1. Authorization Request

Aplikasi mengarahkan browser pengguna ke endpoint authorisasi Keycloak dengan beberapa parameter wajib:

http://localhost:8080/realms/belajar/protocol/openid-connect/auth?client_id=portal-app&redirect_uri=http://localhost:3000/callback&response_type=code&scope=openid&state=acak-1234

Parameter response_type=code menandakan klien menginginkan alur authorization code, client_id menyebut aplikasi, redirect_uri tempat Keycloak mengarahkan kembali, dan state adalah nilai acak untuk proteksi CSRF yang harus diverifikasi saat callback.

#2. Login dan Consent

Keycloak menampilkan halaman login. Setelah kredensial benar, jika aplikasi meminta scope tertentu, pengguna melihat halaman consent yang menjelaskan izin yang diminta. Persetujuan pengguna inilah esensi delegated authorization.

#3. Callback dengan Authorization Code

Setelah login berhasil, Keycloak mengarahkan browser kembali ke redirect_uri dengan menyisipkan code dan state di query string. Aplikasi wajib memverifikasi state sebelum melanjutkan. Kode ini berumur sangat pendek dan hanya bisa dipakai sekali.

#4. Token Exchange

Aplikasi — bukan browser — menukar kode tersebut di token endpoint:

curl -X POST "http://localhost:8080/realms/belajar/protocol/openid-connect/token" \
  -d "grant_type=authorization_code" \
  -d "client_id=portal-app" \
  -d "client_secret=rahasia-aplikasi" \
  -d "code=KODE_DARI_CALLBACK" \
  -d "redirect_uri=http://localhost:3000/callback"

Responnya berisi access token, refresh token, dan ID token sekaligus. Access token dipakai untuk memanggil resource server, ID token memberi informasi identitas pengguna, dan refresh token untuk mendapatkan access token baru.

#PKCE Extension

PKCE (Proof Key for Code Exchange) melindungi authorization code dari penyalahgunaan, terutama pada SPA dan aplikasi mobile yang tidak bisa menyimpan secret. Prinsipnya: aplikasi membuktikan bahwa kode yang dikirim memang miliknya.

• Code verifier — string acak yang dibuat aplikasi sebelum memulai alur.
• Code challenge — turunan verifier yang dikirim ke endpoint authorisasi; metode S256 menghitung hash SHA-256, metode plain mengirim verifier apa adanya.
• Pembuktian — saat menukar kode, aplikasi mengirim verifier; Keycloak menghitung ulang challenge dan mencocokkannya dengan yang disimpan di awal.

Langkah PKCE dalam Authorization Code flow:

Karena aplikasi mobile dan SPA tidak punya client_secret yang aman, PKCE menggantikan peran pembuktian identitas klien. Meskipun aplikasi server-side masih boleh memakai secret, praktik terbaik sekarang menyarankan PKCE di mana-mana.

#Implementasi di Keycloak

Untuk mengaktifkan alur ini di Keycloak:

1. Buat client di realm kalian. Pilih Access Type sesuai kebutuhan: confidential jika aplikasi bisa menyimpan secret, public jika tidak (SPA dan mobile).
2. Set redirect URIs — daftarkan redirect_uri yang valid secara eksplisit. Jangan pernah memakai wildcard yang longgar.
3. Untuk client public, aktifkan PKCE dengan memilih S256 sebagai challenge method.
4. Integrasikan aplikasi contoh — gunakan library OIDC resmi untuk bahasa kalian alih-alih menulis dari nol.
5. Uji alur — jalankan aplikasi, login, lalu periksa token yang diterima. Tools seperti Postman atau ekstensi browser membantu melihat alur lengkap.

#Best Practices

Empat praktik terbaik yang menjaga alur ini tetap aman:

• Selalu gunakan PKCE — bahkan untuk aplikasi server-side, sebagai pertahanan berlapis.
• Amankan redirect URIs — registrasi eksplisit, validasi ketat, hindari wildcard.
• Authorization code berumur pendek — kode harus kedaluwarsa cepat dan hanya sekali pakai.
• Token rotation — rotasi refresh token sehingga token yang dicuri tidak bisa dipakai berulang.

#Penutup

Episode 5 membedah Authorization Code flow: permintaan authorisasi ke endpoint /realms/{realm}/protocol/openid-connect/auth, login dan consent pengguna, callback berisi kode, penukaran kode menjadi access, refresh, dan ID token di token endpoint, hingga ekstensi PKCE yang membuat alur ini aman untuk SPA dan mobile.

Inti yang harus dibawa pulang:

• Password tidak pernah menyentuh aplikasi — itulah kekuatan utama flow ini.
• State wajib diverifikasi — melindungi dari serangan CSRF.
• PKCE melengkapi keamanan — terutama untuk client public tanpa secret.
• Konfigurasi client dan redirect URI menentukan keamanan — lakukan dengan teliti di admin console.

Di episode 6 berikutnya, kita membahas Client Credentials flow — bagaimana service backend berkomunikasi satu sama lain tanpa pengguna, lengkap dengan service accounts dan praktik terbaiknya.