Dalam pengembangan aplikasi web, khususnya saat berinteraksi dengan API, OAuth2, Keycloak, Spring Boot, PHP, maupun aplikasi berbasis form HTML, kita sering menemukan header berikut:

Content-Type: application/x-www-form-urlencoded

Meskipun terlihat sederhana, format ini masih menjadi standar penting dalam banyak protokol autentikasi dan integrasi sistem modern.

Artikel ini membahas cara kerja application/x-www-form-urlencoded, kapan digunakan, perbedaannya dengan JSON, serta berbagai hal yang perlu diperhatikan saat melakukan troubleshooting.

Apa Itu application/x-www-form-urlencoded?

application/x-www-form-urlencoded adalah format pengiriman data HTTP dimana setiap parameter dikirim dalam bentuk pasangan key=value yang dipisahkan oleh karakter &.

Contoh:

username=admin&password=secret123

Ketika dikirim melalui HTTP:

POST /login HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

username=admin&password=secret123

Format ini sudah digunakan sejak awal perkembangan web dan menjadi format default saat sebuah form HTML melakukan submit.

Contoh form HTML:

<form method="POST">
    <input name="username">
    <input name="password">
</form>

Secara otomatis browser akan mengirim data dalam format:

username=admin&password=secret123

Cara Kerja Encoding

Karena HTTP body hanya berupa teks, karakter khusus harus diubah (encoded) agar dapat ditransmisikan dengan aman.

Contoh:

nama=Sena Turana

akan berubah menjadi:

nama=Sena+Turana

atau

nama=Sena%20Turana

Karakter tertentu akan diubah menjadi format URL Encoding:

Contoh:

email=sena@gmail.com

menjadi:

email=sena%40gmail.com

Struktur Data

Format umum:

key1=value1&key2=value2&key3=value3

Contoh:

grant_type=password&
client_id=my-client&
username=admin&
password=secret

Biasanya akan terlihat seperti:

grant_type=password&client_id=my-client&username=admin&password=secret

Mengapa Masih Digunakan?

Meskipun JSON jauh lebih populer saat ini, banyak standar internet masih mewajibkan penggunaan application/x-www-form-urlencoded.

Beberapa contohnya:

• OAuth2 Token Endpoint
• OpenID Connect
• Keycloak Authentication
• Legacy API
• Payment Gateway
• Single Sign-On (SSO)
• Sistem Enterprise Lama

Contoh endpoint OAuth2:

POST /protocol/openid-connect/token

Body:

grant_type=password&
client_id=my-client&
client_secret=secret&
username=admin&
password=password123

Spesifikasi OAuth2 memang mengharuskan parameter token dikirim menggunakan application/x-www-form-urlencoded.

Perbandingan dengan JSON

application/x-www-form-urlencoded

username=admin&password=secret

Header:

Content-Type: application/x-www-form-urlencoded

Kelebihan

• Ringan
• Kompatibel dengan hampir semua platform
• Standar OAuth2
• Mudah diproses server

Kekurangan

• Tidak mendukung struktur kompleks
• Sulit untuk nested object
• Kurang mudah dibaca

application/json

Body:

{
  "username": "admin",
  "password": "secret"
}

Header:

Content-Type: application/json

Kelebihan

• Mudah dibaca
• Mendukung nested object
• Cocok untuk REST API modern

Kekurangan

• Sedikit lebih besar
• Tidak didukung oleh beberapa protokol lama

Contoh di Postman

Saat menguji endpoint OAuth2 atau Keycloak:

Pilih:

Body
  -> x-www-form-urlencoded

Isi:

Postman akan otomatis mengubah menjadi:

grant_type=password&
client_id=my-client&
username=admin&
password=secret

dan menambahkan header:

Content-Type: application/x-www-form-urlencoded

Contoh di Spring Boot

Menggunakan RestTemplate:

MultiValueMap<String, String> params =
        new LinkedMultiValueMap<>();

params.add("grant_type", "password");
params.add("username", username);
params.add("password", password);

HttpHeaders headers = new HttpHeaders();
headers.setContentType(
        MediaType.APPLICATION_FORM_URLENCODED
);

HttpEntity<MultiValueMap<String, String>> request =
        new HttpEntity<>(params, headers);

ResponseEntity<String> response =
        restTemplate.postForEntity(
                url,
                request,
                String.class
        );

Spring akan secara otomatis melakukan URL Encoding pada setiap field sebelum mengirim ke server.

Contoh di Keycloak

Request token ke Keycloak biasanya menggunakan format berikut:

curl -X POST \
  "https://sso.example.com/realms/myrealm/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=my-client" \
  -d "client_secret=my-secret" \
  -d "username=admin" \
  -d "password=secret"

Atau dalam bentuk body mentah:

grant_type=password&
client_id=my-client&
client_secret=my-secret&
username=admin&
password=secret

Keycloak akan melakukan decoding terhadap setiap parameter sebelum memproses autentikasi.

Potensi Masalah yang Sering Terjadi

1. Double Encoding

Misalnya password:

P@ssword123

Sudah di-encode menjadi:

P%40ssword123

Kemudian framework melakukan encode lagi:

P%2540ssword123

Akibatnya server menerima nilai yang berbeda.

2. Karakter Khusus

Password:

admin&123

Jika tidak di-encode:

password=admin&123

Server dapat menganggap:

password=admin

dan

123=

sebagai parameter baru.

3. Perbedaan Hasil Postman dan Aplikasi

Kasus yang sering terjadi:

• Postman berhasil login
• Aplikasi gagal login

Penyebab umum:

• Encoding berbeda
• Header berbeda
• Body tidak sesuai spesifikasi
• Reverse Proxy mengubah request
• Custom middleware memodifikasi parameter

4. Custom Authentication Provider

Pada beberapa implementasi autentikasi, seperti Keycloak yang telah dipasang custom extension, proses validasi username dan password dapat dimodifikasi.

Contohnya:

{
  "error": "invalid_request",
  "error_description": "Username atau Password tidak Ditemukan"
}

Pesan seperti ini bukan merupakan pesan bawaan standar OAuth2 maupun Keycloak default, melainkan biasanya berasal dari custom authenticator atau custom provider yang dibuat oleh tim pengembang.

Bagaimana Server Memproses Data?

Ketika menerima:

username=admin&
password=P%40ssword123

Server akan:

1. Membaca body request
2. Memisahkan berdasarkan karakter &
3. Memisahkan key dan value berdasarkan =
4. Melakukan URL Decoding
5. Memasukkan hasil ke parameter map

Hasil akhirnya:

username = admin
password = P@ssword123

Kapan Sebaiknya Menggunakan application/x-www-form-urlencoded?

Gunakan ketika:

✅ Mengakses OAuth2 Token Endpoint

✅ Integrasi Keycloak

✅ OpenID Connect

✅ Form HTML Tradisional

✅ Integrasi Legacy System

✅ Payment Gateway Lama

Gunakan JSON ketika:

✅ REST API Modern

✅ Microservices

✅ Nested Object

✅ Payload Kompleks

✅ Event Driven Architecture

Kesimpulan

application/x-www-form-urlencoded merupakan format pengiriman data HTTP yang telah digunakan sejak awal perkembangan web dan hingga saat ini masih menjadi standar pada berbagai protokol autentikasi seperti OAuth2 dan OpenID Connect.

Meskipun JSON lebih populer dalam pengembangan API modern, memahami cara kerja encoding, decoding, serta potensi masalah seperti double encoding dan karakter khusus tetap penting bagi developer yang bekerja dengan sistem autentikasi, SSO, Keycloak, maupun integrasi enterprise.

Dalam banyak kasus troubleshooting login yang terlihat sederhana, akar masalah justru berada pada proses URL Encoding yang terjadi sebelum request sampai ke server. Memahami mekanisme ini dapat menghemat banyak waktu saat melakukan investigasi dan debugging integrasi sistem.