Cross-Origin Resource Sharing (CORS)

Penyiapan Contoh konfigurasi

Kebijakan origin yang sama adalah kebijakan keamanan yang diterapkan pada aplikasi web sisi klien (seperti browser web) untuk mencegah interaksi antara resource dari origin yang berbeda. Meskipun berguna untuk mencegah perilaku berbahaya, langkah keamanan ini juga mencegah interaksi yang sah antara origin yang diketahui. Misalnya, skrip pada halaman yang di-host di example.appspot.com mungkin perlu menggunakan resource yang disimpan di Bucket Cloud Storage di example.storage.googleapis.com. Namun, karena keduanya adalah dua asal yang berbeda dari perspektif {i>browser<i}, {i>browser<i} tidak akan mengizinkan skrip dari example.appspot.com untuk mengambil resource dari example.storage.googleapis.com.

Spesifikasi Cross Origin Resource Sharing (CORS) dikembangkan oleh World Wide Web Consortium (W3C) untuk mengatasi batasan ini. Cloud Storage mendukung spesifikasi ini dengan memungkinkan Anda mengonfigurasi bucket untuk mendukung CORS. Melanjutkan contoh sebelumnya, Anda dapat mengonfigurasi bucket example.storage.googleapis.com sehingga browser dapat membagikan resource dengan skrip dari example.appspot.com.

Untuk mengetahui informasi lebih lanjut mengenai komponen konfigurasi CORS, lihat Menetapkan Bucket CORS.

Cara kerja CORS

Ada dua jenis permintaan CORS: sederhana dan preflight. Permintaan sederhana dapat dimulai secara langsung. Permintaan preflight harus mengirimkan permintaan "preflight" awal ke server untuk mendapatkan izin sebelum permintaan utama dapat dilanjutkan. Permintaan akan dijalankan sebelumnya jika salah satu keadaan berikut terpenuhi:

  • Menggunakan metode selain GET, HEAD, atau POST.
  • Menggunakan metode POST dengan Content-Type selain text/plain, application/x-www-form-urlencoded, atau multipart/form-data.
  • Menetapkan header kustom. Misalnya, X-PINGOTHER.

Proses berikut terjadi saat browser membuat permintaan sederhana ke Cloud Storage:

  1. Browser menambahkan header Origin ke permintaan. Header Origin berisi asal sumber daya yang ingin membagikan resource bucket Cloud Storage, misalnya, Origin:https://www.example.appspot.com.

  2. Cloud Storage membandingkan metode HTTP permintaan dan nilai header Origin ke informasi Methods dan Origins di bagian konfigurasi CORS bucket target untuk melihat apakah ada kecocokan. Jika ada, Cloud Storage menyertakan header Access-Control-Allow-Origin di responsnya. Header Access-Control-Allow-Origin berisi nilai header Origin dari permintaan awal.

  3. Browser akan menerima respons dan memeriksa apakah nilai Access-Control-Allow-Origin cocok dengan domain yang ditentukan dalam permintaan asli. Jika cocok, permintaan akan berhasil. Jika tidak cocok, atau jika header Access-Control-Allow-Origin tidak ada dalam respons, permintaan akan gagal.

Permintaan yang di-preflight melakukan langkah-langkah berikut terlebih dahulu. Jika berhasil, permintaan tersebut akan mengikuti proses yang sama dengan permintaan sederhana:

  1. Browser akan mengirimkan permintaan OPTIONS yang berisi Requested Method dan Requested Headers dari permintaan utama.

  2. Cloud Storage merespons kembali dengan nilai metode HTTP dan header yang diizinkan oleh resource yang ditargetkan. Jika salah satu nilai metode atau header dalam permintaan preflight tidak berada dalam kumpulan metode dan header yang diizinkan oleh resource yang ditargetkan, permintaan akan gagal, dan permintaan utama tidak akan dikirim.

Ini adalah deskripsi sederhana tentang CORS. Untuk deskripsi yang lebih lengkap, baca spesifikasi Fetch.

Dukungan CORS Cloud Storage

Dengan Cloud Storage, Anda dapat menetapkan konfigurasi CORS pada level bucket saja. Anda dapat menyiapkan konfigurasi CORS untuk bucket menggunakan berbagai alat: Namun, endpoint Cloud Storage yang berbeda menangani CORS permintaan dengan cara yang berbeda:

  • Endpoint JSON API selalu mengizinkan permintaan CORS dan menampilkan nilai default di header respons CORS, terlepas dari konfigurasi yang ditetapkan pada bucket.

  • Endpoint XML API hanya mengizinkan permintaan CORS berdasarkan konfigurasi pada bucket dan menampilkan nilai header CORS tertentu sebagai respons terhadap konfigurasi tersebut.

  • Endpoint download browser terautentikasi storage.cloud.google.com tidak mengizinkan permintaan CORS. Perlu diperhatikan bahwa konsol Google Cloud menyediakan endpoint ini untuk link URL publik setiap objek.

Anda dapat menggunakan salah satu URL permintaan API XML berikut untuk mendapatkan respons dari Cloud Storage yang berisi header CORS:

storage.googleapis.com/BUCKET_NAME
BUCKET_NAME.storage.googleapis.com

Untuk mengetahui informasi tentang URL permintaan API XML, lihat Meminta Endpoint.

Komponen konfigurasi CORS

Saat menggunakan XML API, nilai yang Anda tetapkan pada konfigurasi CORS bucket akan menentukan header CORS yang ditampilkan Cloud Storage dalam respons HTTP. Saat menggunakan JSON API, Cloud Storage tidak mengevaluasi konfigurasi bucket Anda dan menampilkan nilai header default.

Tabel berikut menjelaskan kolom dalam konfigurasi CORS dan perilaku respons XML API dan JSON API. Untuk mempelajari penggunaan kolom ini, lihat contoh konfigurasi CORS.

Kolom1 Deskripsi Perilaku respons XML API Perilaku respons JSON API
origin Tentukan origin yang ingin Anda izinkan untuk Cross-Origin Resource Sharing (CORS) dengan bucket Cloud Storage ini. Misalnya, https://origin1.example.com. Jika origin dalam permintaan browser cocok dengan origin dalam konfigurasi CORS Anda, Cloud Storage akan menampilkan Access-Control-Allow-Origin ke browser. Jika tidak ada kecocokan, Cloud Storage tidak akan menyertakan Access-Control-Allow-Origin dalam respons. Anda dapat memberikan nilai pengganti yang memberikan akses ke semua origin: <Origin>*</Origin>. Cloud Storage menampilkan header Access-Control-Allow-Origin yang ditetapkan ke asal permintaan.
method

Tentukan metode HTTP yang ingin Anda izinkan untuk berbagi resource lintas origin dengan bucket Cloud Storage ini. Nilai ditampilkan dalam header Access-Control-Allow-Methods sebagai respons terhadap permintaan preflight yang berhasil.

Karena OPTIONS adalah metode standar yang digunakan browser untuk memulai permintaan preflight, Anda tidak boleh menentukan OPTIONS dalam konfigurasi CORS.

Cloud Storage mendukung metode berikut: DELETE, GET, HEAD, POST, PUT.

Cloud Storage memeriksa metode yang dikirim dari browser di header Access-Control-Request-Methods terhadap konfigurasi CORS bucket. Jika tidak ada kecocokan, Cloud Storage akan menampilkan kode respons 200 tanpa header respons CORS.

Cloud Storage menampilkan header Access-Control-Allow-Methods yang ditetapkan ke metode berikut: DELETE, GET, HEAD, PATCH, POST, PUT.
responseHeader Tentukan header yang ingin Anda izinkan untuk Cross-Origin Resource Sharing dengan bucket Cloud Storage ini. Nilai ditampilkan dalam header Access-Control-Allow-Headers sebagai respons terhadap permintaan preflight yang berhasil. Untuk permintaan preflight, Cloud Storage akan memeriksa header yang dikirim dari browser di header Access-Control-Request-Headers terhadap konfigurasi CORS bucket. Jika tidak ada kecocokan, Cloud Storage tidak akan menampilkan header respons CORS. Cloud Storage menampilkan header Access-Control-Allow-Headers yang ditetapkan setara dengan nilai yang ditentukan oleh header Access-Control-Request-Headers.
maxAgeSeconds (opsional) Tentukan jumlah detik yang diizinkan bagi browser untuk membuat permintaan sebelum harus mengulangi permintaan preflight. Ini juga dikenal sebagai waktu berakhirnya cache. Nilai ini ditampilkan dalam header Access-Control-Max-Age sebagai respons terhadap permintaan preflight. Misalnya, 3600 menetapkan waktu berakhirnya cache ke 1 jam. Cloud Storage menampilkan header Access-Control-Max-Age dengan waktu berakhir cache yang ditentukan. Jika Anda menghapus kolom ini, Cloud Storage akan menampilkan nilai default 3600. Cloud Storage menampilkan header Access-Control-Max-Age dengan nilai default 3600.

1 Nama yang didokumentasikan di bidang Kolom bersifat khusus untuk JSON API. Saat menggunakan XML API untuk menetapkan konfigurasi CORS, gunakan format khusus XML.

Menentukan beberapa origin, metode, atau header

Untuk mempelajari cara menetapkan beberapa origin, metode, atau header di CORS , lihat daftar berikut:

  • Saat menggunakan JSON API, Anda dapat menentukan beberapa origin, metode, atau header menggunakan array yang dipisahkan koma. Misalnya, "method": ["GET", "PUT"].

  • Saat menggunakan XML API, Anda bisa menetapkan beberapa origin, metode, atau header menggunakan elemen terpisah. Contoh:

    <Methods>
      <Method>PUT</Method>
      <Method>GET</Method>
    </Methods>
  • Agar permintaan dapat dibuat dari origin mana pun, tetapkan origin ke *. Misalnya, "origin": ["*"] di JSON API atau <Origin>*</Origin> di JSON API API XML. Meskipun origin ini berguna untuk menguji konfigurasi, pada sebagian besar Anda perlu membatasi asal permintaan untuk mencegah penggunaan sumber daya Anda.

Pertimbangan lainnya

Tabel berikut menjelaskan pertimbangan saat membuat permintaan menggunakan kredensial atau header kontrol akses:

Properti atau header Deskripsi Perilaku respons XML API Perilaku respons JSON API
Kredensial Cookie, header otorisasi, atau sertifikat klien TLS. Cloud Storage tidak pernah menampilkan header Access-Control-Allow-Credentials. Kredensial CORS tidak didukung oleh XML API.

Untuk permintaan sederhana, jika permintaan CORS disetujui, header Access-Control-Allow-Credentials akan ditetapkan ke true (benar).

Untuk permintaan preflight, jika Access-Control-Request-Method kosong, Cloud Storage akan menetapkan Access-Control-Allow-Credentials ke true dan menolak permintaan dengan 404 - Not Found.

Header yang terekspos Untuk permintaan preflight, header permintaan Access-Control-Request-Headers menunjukkan header mana yang mungkin disertakan dalam permintaan CORS di masa mendatang. Header respons Access-Control-Expose-Headers disertakan dalam respons server dan menunjukkan kepada klien header mana yang dapat diekspos. Untuk permintaan sederhana, Access-Control-Expose-Headers mencantumkan nilai header respons dalam konfigurasi CORS Anda. Untuk permintaan sederhana, Access-Control-Expose-Headers menampilkan nilai yang ditentukan dalam Access-Control-Request-Headers jika nilai tersebut merupakan bagian dari daftar header HTTP umum.

Mengizinkan bucket mengakses resource eksternal

Terkadang, Anda mungkin ingin mengizinkan skrip yang dihosting di Cloud Storage untuk mengakses resource statis yang dihosting di situs di luar Cloud Storage. Dalam skenario ini, situs menayangkan header CORS sehingga konten di storage.googleapis.com diizinkan untuk diakses.

Sebagai praktik terbaik, Anda harus mendedikasikan bucket tertentu untuk akses data ini. Pendekatan ini mencegah situs Anda mengekspos resource statis secara tidak sengaja ke semua storage.googleapis.com. Misalnya, jika Anda ingin mendedikasikan bucket bernama mybucket untuk akses data, Anda harus meminta situs menayangkan header CORS Access-Control-Allow-Origin: https://mybucket.storage.googleapis.com, bukan Access-Control-Allow-Origin: https://storage.googleapis.com.

Dukungan CORS sisi klien

Sebagian besar browser menggunakan objek XMLHttpRequest untuk membuat permintaan lintas-domain. XMLHttpRequest menangani semua tugas memasukkan header yang tepat dan menangani interaksi CORS dengan server. Anda tidak perlu menambahkan kode baru untuk memanfaatkan dukungan CORS pada bucket Cloud Storage.

Langkah berikutnya