Access-Control-Allow-Headers

Penggunaan

Ketika browser mengirim permintaan preflight OPTIONS, header Access-Control-Request-Headers mendaftar header non-safelisted yang hendak dikirim klien. Server membalas dengan Access-Control-Allow-Headers untuk memastikan header mana saja di antaranya yang diterima.

Header yang termasuk CORS-safelisted selalu diizinkan dan tidak perlu muncul dalam daftar ini. Kumpulan safelisted mencakup Accept, Accept-Language, Content-Language, Content-Type (dengan batasan pada tipe media dan panjang nilai), serta Range (dengan batasan pada formatnya). Mencantumkan header safelisted secara eksplisit akan menghapus batasan tambahan pada nilainya.

Beberapa nama header ditulis sebagai daftar yang dipisahkan koma.

Daftar nama header

Sekumpulan nama header yang dipisahkan koma, yang diterima server pada permintaan sesungguhnya.

Access-Control-Allow-Headers: Content-Type, Authorization

* (wildcard)

Tanda bintang berfungsi sebagai wildcard untuk permintaan tanpa kredensial, sehingga mengizinkan nama header apa pun.

Access-Control-Allow-Headers: *

Catatan

Untuk permintaan dengan kredensial, wildcard * diperlakukan sebagai string literal, bukan sebagai wildcard. Setiap header yang diizinkan harus dicantumkan secara eksplisit ketika kredensial disertakan. Header Authorization tidak pernah tercakup oleh wildcard dan harus selalu disebutkan secara eksplisit.

Contoh

Sebuah permintaan preflight menanyakan apakah Content-Type dan header kustom X-Request-ID diizinkan. Server membenarkan keduanya.

Permintaan

OPTIONS /api/data HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type, X-Request-ID

Respons

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, X-Request-ID
Access-Control-Max-Age: 86400

Server yang menggunakan wildcard untuk permintaan tanpa kredensial merespons dengan satu karakter saja.

Access-Control-Allow-Headers: *

Pemecahan masalah

Kegagalan preflight yang berkaitan dengan header permintaan menghasilkan error di konsol dan memblokir permintaan sesungguhnya.

Konsol menampilkan “Request header field X is not allowed by Access-Control-Allow-Headers in preflight response.” Server tidak mencantumkan nama header tersebut pada nilai Access-Control-Allow-Headers. Tambahkan header yang hilang itu ke respons preflight. Pada nginx: add_header Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID”; Pada Apache: Header set Access-Control-Allow-Headers “Content-Type, Authorization, X-Request-ID”

Respons preflight sama sekali tidak memuat header tersebut. Server menangani permintaan OPTIONS tetapi tidak menyertakan Access-Control-Allow-Headers pada responsnya. Banyak framework mengharuskan konfigurasi CORS secara eksplisit untuk rute preflight. Pastikan handler atau middleware OPTIONS menetapkan header ini bersama Access-Control-Allow-Methods dan Access-Control-Allow-Origin.

Wildcard * tidak bekerja pada permintaan dengan kredensial. Ketika Access-Control-Allow-Credentials bernilai true, wildcard diperlakukan sebagai string literal * dan tidak cocok dengan apa pun. Cantumkan setiap header yang diizinkan secara eksplisit. Header Authorization tidak pernah tercakup oleh wildcard bahkan untuk permintaan tanpa kredensial, dan harus selalu disebutkan.

Nama header tampak bersifat case-sensitive di sebagian server. Menurut protokolnya, nama header HTTP bersifat case-insensitive, tetapi sebagian framework server melakukan pencocokan string yang case-sensitive saat memeriksa daftar yang diizinkan. Permintaan yang mengirim content-type bisa gagal jika server hanya mencantumkan Content-Type. Samakan penulisan huruf dengan yang dikirim klien, atau normalkan kedua sisi menjadi huruf kecil pada konfigurasi CORS.

Mengirim Content-Type: application/json memicu preflight yang tidak terduga. Header Content-Type hanya termasuk safelisted untuk nilai application/x-www-form-urlencoded, multipart/form-data, dan text/plain. Nilai application/json berada di luar safelist sehingga memaksa terjadinya preflight. Tambahkan Content-Type ke daftar Access-Control-Allow-Headers. Untuk memastikan preflight terpicu, buka tab Network pada DevTools dan filter berdasarkan metode untuk menemukan permintaan OPTIONS yang mendahului permintaan sesungguhnya.