CORS Adalah: Cara Kerja, Preflight & Cara Mengatasinya

Satu halaman web modern hampir tidak pernah berdiri sendiri. Saat Anda membuka sebuah situs, browser menarik font dari satu penyedia, gambar dari CDN, dan skrip statistik dari penyedia lain. Semuanya berasal dari domain berbeda, dan tidak satu pun ditahan. Karena itu banyak pengembang terkejut ketika baris JavaScript pertama yang memanggil API mereka sendiri justru berhenti dengan pesan merah di console.

Perbedaannya terletak pada apa yang diminta. Memuat gambar berarti menampilkan sesuatu. Memanggil API berarti membaca datanya. Browser memperlakukan kedua hal itu dengan aturan yang jauh berbeda, dan CORS adalah mekanisme yang menentukan kapan pembacaan lintas domain diizinkan.

CORS Adalah Izin, Bukan Larangan

CORS adalah singkatan dari Cross-Origin Resource Sharing (berbagi sumber daya lintas asal). Ini mekanisme berbasis header HTTP yang memungkinkan sebuah server menyatakan origin mana saja, selain dirinya sendiri, yang boleh membaca responsnya lewat browser.

Perhatikan kata "memungkinkan". Di sinilah letak salah paham yang membuat banyak orang berputar-putar tanpa hasil. Yang memblokir bukan CORS, melainkan same-origin policy (kebijakan asal yang sama), aturan bawaan browser yang sudah ada jauh sebelum CORS lahir. Isinya sederhana: skrip yang berjalan di satu origin tidak boleh membaca data dari origin lain.

Aturan itu bukan kerewelan. Bayangkan Anda membuka internet banking di satu tab, lalu situs berita di tab sebelahnya. Tanpa same-origin policy, skrip di situs berita bisa memanggil alamat internet banking Anda sambil membawa cookie sesi yang masih aktif. Saldo dan riwayat transaksi Anda terbaca tanpa satu pun peringatan.

CORS adalah pintu resmi yang boleh dibuka pemilik server di tembok tersebut. Lewat beberapa header respons, server berkata kepada browser: "origin ini saya kenal, silakan izinkan dia membaca." Tanpa header itu, browser memakai aturan bawaannya dan menolak.

Konsekuensinya, pertanyaan "bagaimana cara mematikan CORS" sebenarnya terbalik arah. CORS bukan sesuatu yang menyala lalu perlu dipadamkan. Yang perlu Anda lakukan justru sebaliknya: menyalakannya di server penyedia data.

Aturan ini juga tidak beku. CORS pernah terbit sebagai W3C Recommendation pada 16 Januari 2014. Dokumen itu dinyatakan usang pada Agustus 2017 karena tidak lagi menggambarkan perilaku browser yang sesungguhnya, dan rujukan yang berlaku hari ini adalah Fetch Standard dari WHATWG.

Menghitung Origin: Skema, Host, dan Port

Sebelum melangkah lebih jauh, Anda perlu tahu persis apa yang dihitung browser sebagai "asal yang sama". Origin terdiri dari tiga bagian, dan ketiganya harus identik: skema (protokol), host, dan port.

Berikut perbandingannya bila halaman Anda berada di https://tokosaya.co.id:

Baris ketiga adalah yang paling sering mengejutkan. Meletakkan API di sebuah subdomain terasa seperti "masih rumah sendiri", padahal bagi browser itu origin yang sepenuhnya berbeda. Baris kedua juga penting: memindahkan situs dari HTTP ke HTTPS mengubah originnya, sehingga konfigurasi lama bisa mendadak berhenti bekerja.

Soal port, perlu diingat bahwa nomor bawaan tidak ditulis di URL tetapi tetap dihitung. HTTPS memakai 443 dan HTTP memakai 80. Karena itu server pengembangan di localhost:3000 dan localhost:8000 adalah dua origin berbeda, dan pasangan itulah yang paling sering memicu error CORS pertama seorang pengembang.

Istilah site dan origin tidak sama, meski sering dipakai bergantian. Cookie bekerja pada tingkat site, sehingga tokosaya.co.id dan api.tokosaya.co.id dianggap satu keluarga. CORS bekerja pada tingkat origin yang jauh lebih ketat, dan di sana keduanya adalah orang asing.

Request Anda Sebenarnya Tetap Sampai ke Server

Bagian ini yang paling sering disalahpahami, dan memahaminya akan menghemat banyak waktu Anda saat menelusuri masalah.

Ketika JavaScript memanggil sebuah alamat lintas origin, urutan sesungguhnya adalah:

1. Browser menambahkan header Origin berisi alamat halaman Anda. Header ini disisipkan browser sendiri dan tidak bisa diubah dari JavaScript.
2. Request dikirim seperti biasa ke server tujuan.
3. Server menerima, memproses, dan membalas. Server tidak menolak apa pun; ia bekerja normal.
4. Browser memeriksa header izin pada respons yang datang.
5. Bila izinnya tidak ada atau tidak cocok, browser membuang respons itu dan melemparkan error ke JavaScript.

Langkah ketiga adalah kuncinya. Server sudah bekerja. Bila request Anda berupa POST yang menyimpan pesanan ke database, pesanan itu tersimpan — meski console Anda merah dan JavaScript tidak menerima apa-apa.

Inilah sebabnya dua gejala yang terasa janggal itu masuk akal. Log server menunjukkan status 200 padahal browser mengatakan gagal, dan data ikut berubah padahal tampilan tidak pernah diperbarui. Blokirnya terjadi di sisi browser, pada detik terakhir, setelah semua pekerjaan di seberang sana selesai.

Diagram alur CORS: server tetap memproses request, lalu browser yang menahan responsnya dari JavaScript.

Cara paling cepat membuktikannya adalah menguji alamat yang sama dengan curl. Alat baris perintah bukan browser, sehingga ia tidak menjalankan same-origin policy sama sekali:

curl -i -H "Origin: https://tokosaya.co.id" https://api.tokosaya.co.id/produk

Bila perintah itu mengembalikan data dengan status 200 sementara browser tetap menolak, Anda sudah memastikan satu hal penting: server hidup dan endpointnya benar. Yang kurang hanya header izin. Periksa apakah balasannya memuat baris Access-Control-Allow-Origin.

Dua Jalur Request: Sederhana dan Preflight

Browser tidak memperlakukan semua request lintas origin dengan cara yang sama. Ada dua jalur.

Jalur pertama adalah simple request, yaitu request yang langsung dikirim tanpa permisi lebih dulu. Sebuah request masuk kategori ini hanya bila seluruh syarat berikut terpenuhi:

1. Metodenya GET, HEAD, atau POST: selain ketiganya otomatis keluar dari jalur ini.
2. Header yang Anda pasang sendiri hanya dari daftar aman: Accept, Accept-Language, Content-Language, Content-Type, dan Range dengan satu rentang nilai.
3. Nilai Content-Type terbatas pada tiga pilihan: application/x-www-form-urlencoded, multipart/form-data, atau text/plain.
4. Tidak ada event listener pada XMLHttpRequest.upload.
5. Tidak memakai objek ReadableStream.

Bacalah syarat nomor tiga sekali lagi. application/json tidak ada di sana. Padahal hampir semua panggilan REST API modern mengirim data dalam format JSON dengan Content-Type: application/json. Menambahkan header Authorization untuk token juga langsung melanggar syarat nomor dua.

Akibatnya, pekerjaan sehari-hari seorang pengembang API nyaris selalu jatuh ke jalur kedua: preflight. Di jalur ini browser mengirim satu request pendahuluan bermetode OPTIONS untuk bertanya lebih dulu. Request itu membawa dua header: Access-Control-Request-Method berisi metode yang hendak dipakai nanti, dan Access-Control-Request-Headers berisi header yang hendak dikirim nanti.

Server harus menjawabnya dengan izin yang sesuai. Bila jawabannya memuaskan, browser baru mengirim request yang sebenarnya. Bila tidak, request asli tidak pernah dikirim sama sekali.

Diagram CORS membandingkan jalur sederhana satu perjalanan dengan jalur preflight dua perjalanan.

Ada akibat praktis yang sering terlewat di sini. Pada jalur preflight, kegagalan terjadi sebelum kode Anda di server sempat berjalan. Bila titik henti di dalam fungsi endpoint tidak pernah tersentuh, kemungkinan besar yang gagal adalah OPTIONS-nya. Framework yang tidak menyiapkan jawaban untuk metode itu biasanya membalas 404 atau 405, dan browser membaca itu sebagai penolakan.

Header CORS yang Perlu Anda Kenali

Seluruh percakapan izin ini berlangsung lewat sembilan header. Enam dikirim server, tiga dikirim browser.

Ada satu batasan yang jarang disadari sampai seseorang membutuhkannya. Meski respons berhasil dibaca, JavaScript tidak otomatis bisa membaca semua header di dalamnya. Hanya tujuh yang terbuka secara bawaan: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified, dan Pragma.

Header di luar tujuh itu harus disebut satu per satu di Access-Control-Expose-Headers. Misalnya API Anda mengirim jumlah total data lewat header buatan sendiri bernama X-Total-Count untuk penomoran halaman. JavaScript akan membacanya sebagai null sampai header itu didaftarkan.

Soal Cookie dan Kenapa Tanda Bintang Ditolak

Aturan berubah drastis begitu request Anda perlu membawa kredensial: cookie, token otentikasi HTTP, atau sertifikat klien. Secara bawaan browser tidak menyertakan cookie pada request lintas origin, jadi Anda harus memintanya secara eksplisit:

fetch("https://api.tokosaya.co.id/profil", {
  credentials: "include"
});

Sisi server pun harus menyetujuinya dengan Access-Control-Allow-Credentials: true. Bagian yang menjebak datang berikutnya: saat kredensial ikut serta, tanda bintang dilarang.

Access-Control-Allow-Origin: * akan ditolak browser. Larangan yang sama berlaku untuk Access-Control-Allow-Headers, Access-Control-Allow-Methods, dan Access-Control-Expose-Headers — semuanya harus disebut satu per satu.

Alasannya masuk akal begitu Anda mengingat contoh internet banking tadi. Tanda bintang berarti "siapa pun boleh". Menggabungkannya dengan kredensial sama saja mengizinkan situs mana pun membaca data pribadi pengunjung Anda memakai sesi milik pengunjung itu sendiri.

Karena * tidak lagi bisa dipakai, server yang melayani banyak origin harus menyusun daftar origin tepercaya. Periksa header Origin yang masuk terhadap daftar itu, lalu balas dengan alamat yang cocok. Jangan pernah menyalin nilai Origin begitu saja tanpa pemeriksaan — akibatnya kita bahas di bagian keamanan nanti.

Membaca Pesan Error CORS di Console

Pesan error CORS panjang dan terlihat menakutkan, padahal isinya cukup rapi. Kalimat kuncinya selalu berada di belakang tanda titik dua.

Firefox memakai kalimat pembuka yang berbeda, yaitu Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource, tetapi sebab dan perbaikannya sama persis.

Jebakan strict-origin-when-cross-origin

Ada satu tulisan yang membuat banyak orang mengejar arah yang salah. Di tab Network pada DevTools, kolom Referrer Policy sering menampilkan strict-origin-when-cross-origin. Karena memuat kata "cross-origin" dan muncul tepat di sebelah request yang gagal, tulisan itu mudah dikira penyebabnya.

Padahal itu bukan pesan kesalahan dan tidak berhubungan dengan CORS. Ia adalah nilai bawaan Referrer-Policy, aturan terpisah yang mengatur seberapa banyak informasi alamat halaman asal Anda dibocorkan ke situs tujuan. Nilai itu menjadi bawaan di Chrome 85 pada Agustus 2020 dan Firefox 87 pada Maret 2021, sebagai langkah menjaga privasi pengguna.

Perilakunya: alamat lengkap dikirim untuk request satu origin, dan hanya nama originnya saja untuk lintas origin dengan tingkat keamanan setara. Saat berpindah dari HTTPS ke HTTP, tidak ada yang dikirim. Mengubah nilai itu tidak akan menyelesaikan error CORS Anda. Abaikan barisnya, lalu kembali membaca pesan di tab Console.

Memperbaiki CORS di Sisi yang Benar

Ini kalimat yang perlu Anda pegang: perbaikan selalu berada di server yang memiliki data, bukan di aplikasi frontend yang memanggilnya. Tidak ada konfigurasi di sisi JavaScript yang bisa memberi izin kepada diri sendiri.

Bila server itu milik Anda, tempat pemasangannya tergantung pada perangkat yang melayaninya. Pada Nginx, tambahkan di dalam blok lokasi API Anda:

location /api/ {
    add_header Access-Control-Allow-Origin "https://tokosaya.co.id" always;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Content-Type, Authorization" always;
    add_header Access-Control-Max-Age 7200 always;

    if ($request_method = OPTIONS) {
        return 204;
    }
}

Kata always di ujung setiap baris bukan hiasan. Tanpa kata itu, Nginx hanya mengirim header pada respons yang berhasil. Respons 401 atau 500 dari API Anda kehilangan izinnya, lalu muncul di browser sebagai error CORS yang menyesatkan. Blok if di bawahnya menjawab preflight dengan status 204 tanpa isi.

Pada Apache, pekerjaan yang sama dilakukan modul mod_headers:

<IfModule mod_headers.c>
    Header always set Access-Control-Allow-Origin "https://tokosaya.co.id"
    Header always set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
    Header always set Access-Control-Allow-Headers "Content-Type, Authorization"
</IfModule>

Pengguna Laravel tidak perlu memasang paket tambahan, karena middleware HandleCors sudah aktif secara bawaan. Yang sering terjadi justru sebaliknya: orang menyunting config/cors.php yang belum ada, lalu bingung mengapa tidak ada perubahan. Terbitkan berkasnya lebih dulu dengan php artisan config:publish cors, sesuaikan isinya, lalu bersihkan cache konfigurasi lewat php artisan config:clear.

Pada Express, satu baris middleware sudah memadai:

const cors = require("cors");
app.use("/api", cors({ origin: "https://tokosaya.co.id" }));

Mengubah konfigurasi di level web server menuntut akses yang tidak selalu tersedia pada paket hosting bersama. Bila Anda memerlukan kendali penuh atas berkas konfigurasi Nginx atau Apache, VPS Indonesia memberi akses root sejak awal.

Bila API-nya milik orang lain

Anda tidak bisa memasang header di server yang bukan milik Anda. Jalan keluarnya adalah memindahkan panggilan itu ke backend Anda sendiri. JavaScript memanggil alamat di origin Anda, backend meneruskannya ke API tujuan, lalu mengembalikan hasilnya. Karena backend bukan browser, ia tidak terikat same-origin policy. Pola ini dikenal sebagai proxy, dan sekalian menyembunyikan kunci API Anda dari pengunjung.

Soal jalan pintas yang beredar

Dua jalan pintas paling populer perlu dinilai apa adanya.

Extension browser bertuliskan "Allow CORS" memang membuat error hilang di layar Anda. Masalahnya, ia hanya mengubah perilaku browser di komputer Anda sendiri. Pengunjung situs Anda tidak memasangnya, sehingga aplikasi tetap gagal di perangkat mereka. Inilah sebabnya sebagian bug terasa "sudah beres" lalu muncul kembali setelah rilis.

Proxy CORS publik gratisan memindahkan lalu lintas Anda melewati server milik orang yang tidak Anda kenal. Seluruh isi request, termasuk token dan data pengguna, melewati mesin tersebut. Layanan semacam ini masuk akal untuk percobaan sesaat, tetapi tidak untuk aplikasi yang dipakai orang.

Sisi Lain CORS yang Perlu Anda Pertimbangkan

Setelah semua manfaatnya, ada beberapa hal yang perlu Anda ketahui sebelum menganggap urusan ini selesai.

Preflight menambah satu perjalanan bolak-balik. Setiap request non-sederhana berarti dua kali komunikasi ke server, dan pada koneksi seluler dengan jeda 150 milidetik tambahan itu terasa. Penawarnya adalah Access-Control-Max-Age, tetapi nilai bawaannya hanya 5 detik — praktis tidak menyimpan apa pun. Anda perlu menaikkannya sendiri, dengan catatan setiap browser punya batas atas:

Nilai di atas batas tidak ditolak, melainkan diturunkan diam-diam ke batas browser. Menulis 86400 pada konfigurasi Anda akan tetap berlaku 2 jam di Chrome.

CORS tidak menggantikan pengamanan di sisi server. Aturan ini hanya mengatur perilaku browser. Siapa pun bisa memanggil endpoint Anda langsung dengan curl, Postman, atau skrip sederhana, dan seluruh mekanisme CORS tidak berlaku di sana. Endpoint yang seharusnya rahasia tetap membutuhkan otentikasi dan otorisasi yang benar.

CORS juga bukan pertahanan terhadap CSRF. Ingat kembali bahwa request tetap terkirim dan tetap diproses server; yang ditahan hanya pembacaan responsnya. Serangan yang tujuannya mengubah data — bukan membacanya — tidak terhalang sama sekali. Untuk itu Anda tetap memerlukan token CSRF dan atribut SameSite pada cookie.

Konfigurasi yang longgar berubah menjadi kerentanan. Ini bagian yang paling perlu kehati-hatian, karena empat kesalahan berikut justru lahir dari niat "supaya berhenti error":

1. Memantulkan Origin apa adanya: server menyalin nilai header Origin yang masuk langsung ke Access-Control-Allow-Origin. Digabung dengan Allow-Credentials: true, situs mana pun di internet dapat membaca data ter-otentikasi pengunjung Anda. Inilah kesalahan CORS yang paling berbahaya sekaligus paling sering ditemukan.
2. Mempercayai nilai null: browser mengirim Origin: null dari dokumen ber-sandbox, skema data:, dan berkas lokal. Menyetujui null berarti memberi izin yang dapat dipicu lewat sebuah iframe ber-sandbox.
3. Pencocokan subdomain yang keliru: daftar izin yang diperiksa dengan "berakhiran tokosaya.co.id" dapat ditembus dengan mendaftarkan domain jahattokosaya.co.id. Pemeriksaan "berawalan" ditembus dengan tokosaya.co.id.jahat.net.
4. Mengizinkan subdomain HTTP pada situs HTTPS: satu subdomain tanpa enkripsi di daftar izin membuka jalan penyadapan. Penyerang di tengah jalur dapat menyisipkan respons palsu pada lalu lintas HTTP itu.

Ketiga poin pertama punya obat yang sama. Susun daftar origin tepercaya secara eksplisit, cocokkan dengan perbandingan yang utuh, dan jangan pernah membentuknya dari masukan yang dikirim klien. Bila Anda sedang menelusuri lubang keamanan sisi browser, kerabat dekat pembahasan ini adalah XSS.

Empat kesalahan konfigurasi CORS: memantulkan Origin, mempercayai null, cocok sebagian, dan subdomain HTTP.

CORS di Dunia Geodesi: InaCORS dan Stasiun GNSS

Bila Anda tiba di halaman ini sambil mencari sesuatu tentang pemetaan atau alat ukur tanah, singkatan yang Anda maksud kemungkinan besar berbeda.

Di bidang geodesi dan survei, CORS adalah kependekan dari Continuously Operating Reference Station. Itu adalah stasiun penerima sinyal GNSS (Global Navigation Satellite System) yang dipasang permanen di satu titik dan merekam data satelit 24 jam sehari, tujuh hari seminggu. Rekaman terus-menerus itu berfungsi sebagai titik ikat. Alat ukur di lapangan membandingkan bacaannya dengan data stasiun terdekat, sehingga ketelitian posisi naik dari kisaran meter menjadi sentimeter.

Di Indonesia, jaringan stasiun semacam ini dikelola Badan Informasi Geospasial (BIG) dengan nama InaCORS. Perannya adalah jaring kontrol geodetik aktif yang menjadi tulang punggung Sistem Referensi Geospasial Indonesia (SRGI). Dari sanalah pengukuran dan pemetaan di seluruh wilayah Indonesia memperoleh satu acuan yang sama. Sebagian stasiun InaCORS juga menyumbang data untuk Indonesia Tsunami Early Warning System (InaTEWS) serta pemodelan Total Electron Content di lapisan ionosfer.

Jadi kedua CORS ini sama sekali tidak berkerabat. Yang satu mengatur izin membaca data antar-alamat web, yang lain merekam sinyal satelit untuk menentukan posisi di permukaan bumi. Kebetulan singkatannya sama.

Pertanyaan yang Sering Muncul Seputar CORS

Apa yang dimaksud dengan CORS?

CORS adalah mekanisme berbasis header HTTP yang memungkinkan server memberi izin kepada origin tertentu untuk membaca responsnya lewat browser. Tanpa izin itu, browser menerapkan same-origin policy dan menolak menyerahkan data tersebut ke JavaScript.

Apa arti CORS?

CORS adalah singkatan dari Cross-Origin Resource Sharing, yang berarti berbagi sumber daya lintas asal. Di bidang geodesi, singkatan yang sama berarti Continuously Operating Reference Station.

Kenapa kena CORS?

Karena halaman Anda memanggil alamat dengan skema, host, atau port yang berbeda, sementara server tujuan tidak mengirim header Access-Control-Allow-Origin yang cocok. Penyebab tersering pada tahap pengembangan adalah frontend dan backend berjalan di dua nomor port yang berbeda pada satu komputer.

Apakah CORS bisa dimatikan dari sisi frontend?

Tidak bisa. Aturannya dijalankan browser, dan tidak ada konfigurasi JavaScript yang dapat memberi izin kepada dirinya sendiri. Perbaikannya harus dilakukan di server pemilik data, atau lewat proxy di backend Anda sendiri bila server itu bukan milik Anda.

CORS GPS adalah?

Itu merujuk pada stasiun referensi GNSS permanen yang dipakai untuk pengukuran presisi, bukan pada teknologi web. Di Indonesia jaringannya bernama InaCORS dan dikelola Badan Informasi Geospasial.

Kesimpulan

CORS adalah mekanisme izin, bukan penghalang. Yang menahan JavaScript membaca data lintas alamat adalah same-origin policy bawaan browser. CORS justru cara resmi bagi pemilik server untuk melonggarkannya, sehingga perbaikan selalu dilakukan di server yang memiliki data, tidak pernah di sisi frontend.

Tiga hal layak Anda ingat saat berhadapan dengan errornya. Pertama, request Anda sudah sampai dan sudah diproses server, sehingga log 200 yang berbarengan dengan console merah bukan hal aneh. Kedua, Content-Type: application/json dan header Authorization menyeret request Anda ke jalur preflight, jadi pastikan server menjawab metode OPTIONS dengan benar. Ketiga, tulisan strict-origin-when-cross-origin di DevTools adalah nilai bawaan Referrer-Policy, bukan penyebab masalah.

Terakhir, tahan keinginan memakai Access-Control-Allow-Origin: * atau memantulkan header Origin hanya supaya pesan merahnya berhenti. Menyusun daftar origin secara eksplisit hanya butuh beberapa menit, dan itulah yang memisahkan konfigurasi yang berfungsi dari konfigurasi yang membuka pintu ke data pengunjung Anda.

Semoga artikel ini membantu.