Dukungan Cross-Origin Resource Sharing (CORS) untuk Azure Storage

Artikel
07/11/2023

Dimulai dengan versi 2013-08-15, layanan penyimpanan Azure mendukung Cross-Origin Resource Sharing (CORS) untuk layanan Blob, Table, dan Queue. Layanan File mendukung CORS yang dimulai dengan versi 2015-02-21.

CORS adalah fitur HTTP yang memungkinkan aplikasi web berjalan di bawah satu domain untuk mengakses sumber daya di domain lain. Browser web menerapkan pembatasan keamanan yang dikenal sebagai kebijakan asal yang sama yang mencegah halaman web memanggil API di domain yang berbeda; CORS menyediakan cara yang aman untuk memungkinkan satu domain (domain asal) untuk memanggil API di domain lain. Lihat spesifikasi CORS untuk detail tentang CORS.

Anda dapat mengatur aturan CORS satu per satu untuk setiap layanan Azure Storage, dengan memanggil Atur Properti Blob Service, Mengatur Properti Layanan File, Mengatur Properti Layanan Antrean, dan Mengatur Properti Layanan Tabel. Setelah Anda menetapkan aturan CORS untuk layanan, maka permintaan resmi yang dibuat untuk layanan dari domain yang berbeda akan dievaluasi untuk menentukan apakah itu diizinkan sesuai dengan aturan yang telah Anda tentukan.

Penting

CORS bukanlah mekanisme otorisasi. Setiap permintaan yang dibuat terhadap sumber daya penyimpanan saat CORS diaktifkan harus memiliki header otorisasi yang valid, atau harus dibuat terhadap sumber daya publik.

CORS didukung untuk semua jenis akun penyimpanan kecuali untuk akun penyimpanan v1 atau v2 tujuan umum di tingkat performa premium.

Memahami permintaan CORS

Permintaan CORS dari domain asal dapat terdiri dari dua permintaan terpisah:

Permintaan preflight, yang menanyakan pembatasan CORS yang diberlakukan oleh layanan. Permintaan preflight diperlukan kecuali metode permintaan adalah metode sederhana, yang berarti GET, HEAD, atau POST.
Permintaan yang sebenarnya, dibuat karena sumber daya yang diinginkan.

Permintaan Preflight

Permintaan preflight meminta pembatasan CORS yang telah ditetapkan untuk layanan penyimpanan oleh pemilik akun. Browser web (atau agen pengguna lainnya) mengirimkan permintaan OPTIONS yang mencakup header permintaan, metode, dan domain asal. Layanan penyimpanan mengevaluasi operasi yang dimaksudkan berdasarkan serangkaian aturan CORS yang telah dikonfigurasi sebelumnya yang menentukan domain asal, metode permintaan, dan header permintaan mana yang dapat ditentukan pada permintaan aktual terhadap sumber daya penyimpanan.

Jika CORS diaktifkan untuk layanan dan ada aturan CORS yang cocok dengan permintaan preflight, layanan merespons dengan kode status 200 (OK), dan menyertakan header Access-Control yang diperlukan dalam respons.

Jika CORS tidak diaktifkan untuk layanan atau tidak ada aturan CORS yang cocok dengan permintaan preflight, layanan akan merespons dengan kode status 403 (Terlarang).

Jika permintaan OPTIONS tidak berisi header CORS yang diperlukan (header Origin dan Access-Control-Request-Method), layanan akan merespons dengan kode status 400 (Permintaan buruk).

Perhatikan bahwa permintaan preflight dievaluasi terhadap layanan (Blob, File, Antrean, atau Tabel) dan bukan terhadap sumber daya yang diminta. Pemilik akun harus telah mengaktifkan CORS dengan mengatur properti layanan akun yang sesuai agar permintaan berhasil.

Permintaan Aktual

Setelah permintaan preflight diterima dan respons dikembalikan, browser akan mengirimkan permintaan aktual terhadap sumber daya penyimpanan. Browser akan segera menolak permintaan yang sebenarnya jika permintaan preflight ditolak.

Permintaan aktual diperlakukan sebagai permintaan normal terhadap layanan penyimpanan. Kehadiran header Asal menunjukkan bahwa permintaan adalah permintaan CORS dan layanan akan memeriksa aturan CORS yang cocok. Jika kecocokan ditemukan, header Access-Control ditambahkan ke respons dan dikirim kembali ke klien. Jika kecocokan tidak ditemukan, header CORS Access-Control tidak dikembalikan.

Mengaktifkan CORS untuk Azure Storage

Aturan CORS diatur pada tingkat layanan, jadi Anda perlu mengaktifkan atau menonaktifkan CORS untuk setiap layanan (Blob, File, Antrean, dan Tabel) secara terpisah. Secara default, CORS dinonaktifkan untuk setiap layanan. Untuk mengaktifkan CORS, Anda perlu mengatur properti layanan yang sesuai menggunakan versi 2013-08-15 atau yang lebih baru untuk layanan Blob, Antrean, dan Tabel, atau versi 2015-02-21 atau untuk layanan File. Anda mengaktifkan CORS dengan menambahkan aturan CORS ke properti layanan. Untuk detail tentang cara mengaktifkan atau menonaktifkan CORS untuk layanan dan cara mengatur aturan CORS, lihat Mengatur Properti Layanan Blob, Mengatur Properti Layanan File, Mengatur Properti Layanan Tabel, dan Mengatur Properti Layanan Antrean.

Berikut adalah sampel dari satu aturan CORS, yang ditentukan melalui Set Service Properties operasi:

<Cors>
    <CorsRule>  
        <AllowedOrigins>http://*.contoso.com, http://www.fabrikam.com</AllowedOrigins>  
        <AllowedMethods>PUT,GET</AllowedMethods>  
        <AllowedHeaders>x-ms-meta-data*,x-ms-meta-target*,x-ms-meta-abc</AllowedHeaders>  
        <ExposedHeaders>x-ms-meta-*</ExposedHeaders>  
        <MaxAgeInSeconds>200</MaxAgeInSeconds>  
    </CorsRule>  
<Cors>

Setiap elemen yang disertakan dalam aturan CORS dijelaskan di bawah ini:

AllowedOrigins: Domain asal yang diizinkan untuk membuat permintaan terhadap layanan penyimpanan melalui CORS. Domain asal adalah domain tempat permintaan berasal. Perhatikan bahwa asal harus sama persis dengan kecocokan peka huruf besar/kecil dengan asal yang dikirim oleh usia pengguna ke layanan.

Anda dapat menggunakan karakter kartubebas '*' sebagai pengganti domain tertentu untuk memungkinkan semua domain asal membuat permintaan melalui CORS. Anda juga dapat menggunakan karakter kartubebas sebagai pengganti subdomain untuk memungkinkan semua subdomain domain tertentu membuat permintaan melalui CORS. Dalam contoh di atas, semua subdomain contoso.com dapat membuat permintaan melalui CORS, sementara hanya permintaan dari www subdomain fabrikam.com yang diizinkan melalui CORS.
AllowedMethods: Metode (kata kerja permintaan HTTP) yang dapat digunakan domain asal untuk permintaan CORS. Dalam contoh di atas, hanya permintaan PUT dan GET yang diizinkan.
AllowedHeaders: Header permintaan yang dapat ditentukan domain asal pada permintaan CORS. Dalam contoh di atas, semua header metadata yang dimulai dengan x-ms-meta-data, x-ms-meta-target, dan x-ms-meta-abc diizinkan. Perhatikan bahwa karakter kartubebas '*' menunjukkan bahwa header apa pun yang dimulai dengan awalan yang ditentukan diizinkan.
ExposedHeaders: Header respons yang dapat dikirim sebagai respons terhadap permintaan CORS dan diekspos oleh browser ke penerbit permintaan. Dalam contoh di atas, browser diinstruksikan untuk mengekspos header apa pun yang dimulai dengan x-ms-meta.
MaxAgeInSeconds: Jumlah waktu maksimum browser harus menyimpan cache permintaan OPSI preflight.

Layanan penyimpanan Azure mendukung penentuan header awalan untuk elemen AllowedHeaders dan ExposedHeaders . Untuk memperbolehkan kategori header, Anda dapat menentukan awalan umum untuk kategori tersebut. Misalnya, menentukan sebagai header awalan x-ms-meta* menetapkan aturan yang akan cocok dengan semua header yang dimulai dengan x-ms-meta.

Batasan berikut berlaku untuk aturan CORS:

Anda dapat menentukan hingga lima aturan CORS per layanan penyimpanan (Blob, File, Tabel, dan Antrean).
Ukuran maksimum semua pengaturan aturan CORS pada permintaan, tidak termasuk tag XML, tidak boleh melebihi 2 KiB.
Panjang header yang diizinkan, header yang diekspos, atau asal yang diizinkan tidak boleh melebihi 256 karakter.
Header yang diizinkan dan header yang diekspos mungkin:
- Header harfiah, di mana nama header yang tepat disediakan, seperti x-ms-meta-processed. Maksimal 64 header literal dapat ditentukan pada permintaan.
- Header awalan, di mana awalan header disediakan, seperti x-ms-meta-data*. Menentukan awalan dengan cara ini memungkinkan atau mengekspos header apa pun yang dimulai dengan awalan yang diberikan. Maksimal dua header awalan dapat ditentukan pada permintaan.
Metode (atau kata kerja HTTP) yang ditentukan dalam elemen AllowedMethods harus sesuai dengan metode yang didukung oleh API layanan penyimpanan Azure. Metode yang didukung adalah DELETE, GET, HEAD, MERGE, POST, PATCH, OPTIONS dan PUT.

Memahami logika evaluasi aturan CORS

Ketika layanan penyimpanan menerima permintaan preflight atau aktual, layanan tersebut mengevaluasi permintaan tersebut berdasarkan aturan CORS yang telah Anda tetapkan untuk layanan melalui operasi Set Service Properties yang sesuai. Aturan CORS dievaluasi dalam urutan di mana aturan tersebut ditetapkan dalam isi permintaan operasi Set Service Properties.

Aturan CORS dievaluasi sebagai berikut:

Pertama, domain asal permintaan diperiksa terhadap domain yang tercantum untuk AllowedOrigins elemen . Jika domain asal disertakan dalam daftar, atau semua domain diizinkan dengan karakter kartubebas '*', maka evaluasi aturan akan dilanjutkan. Jika domain asal tidak disertakan, maka permintaan gagal.
Selanjutnya, metode (atau kata kerja HTTP) permintaan diperiksa terhadap metode yang tercantum dalam AllowedMethods elemen . Jika metode disertakan dalam daftar, maka evaluasi aturan akan dilanjutkan; jika tidak, maka permintaan gagal.
Jika permintaan cocok dengan aturan di domain asalnya dan metodenya, aturan tersebut dipilih untuk memproses permintaan dan tidak ada aturan lebih lanjut yang dievaluasi. Namun, sebelum permintaan dapat berhasil, header apa pun yang ditentukan pada permintaan diperiksa terhadap header yang tercantum dalam AllowedHeaders elemen . Jika header yang dikirim tidak cocok dengan header yang diizinkan, permintaan gagal.

Karena aturan diproses dalam urutan yang ada dalam isi permintaan, praktik terbaik merekomendasikan agar Anda menentukan aturan yang paling ketat sehubungan dengan asal terlebih dahulu dalam daftar, sehingga ini dievaluasi terlebih dahulu. Tentukan aturan yang kurang ketat – misalnya, aturan untuk mengizinkan semua asal – di akhir daftar.

Contoh – Evaluasi aturan CORS

Contoh berikut menunjukkan isi permintaan parsial untuk operasi guna menetapkan aturan CORS untuk layanan penyimpanan. Lihat Mengatur Properti Blob Service, Mengatur Properti Layanan File, Mengatur Properti Layanan Antrean, dan Mengatur Properti Layanan Tabel untuk detail tentang membuat permintaan.

<Cors>  
    <CorsRule>  
        <AllowedOrigins>http://www.contoso.com</AllowedOrigins>  
        <AllowedMethods>PUT,HEAD</AllowedMethods>  
        <MaxAgeInSeconds>5</MaxAgeInSeconds>  
        <ExposedHeaders>x-ms-*</ExposedHeaders>  
        <AllowedHeaders>x-ms-blob-content-type, x-ms-blob-content-disposition</AllowedHeaders>  
    </CorsRule>  
    <CorsRule>  
        <AllowedOrigins>*</AllowedOrigins>  
        <AllowedMethods>PUT,GET</AllowedMethods>  
        <MaxAgeInSeconds>5</MaxAgeInSeconds>  
        <ExposedHeaders>x-ms-*</ExposedHeaders>  
        <AllowedHeaders>x-ms-blob-content-type, x-ms-blob-content-disposition</AllowedHeaders>  
    </CorsRule>  
    <CorsRule>  
        <AllowedOrigins>http://www.contoso.com</AllowedOrigins>  
        <AllowedMethods>GET</AllowedMethods>  
        <MaxAgeInSeconds>5</MaxAgeInSeconds>  
        <ExposedHeaders>x-ms-*</ExposedHeaders>  
        <AllowedHeaders>x-ms-client-request-id</AllowedHeaders>  
    </CorsRule>  
</Cors>

Selanjutnya, pertimbangkan permintaan CORS berikut:

Metode	Asal	Header permintaan	Kecocokan Aturan	Hasil
PUT	`http://www.contoso.com`	`x-ms-blob-content-type`	Aturan pertama	Berhasil
GET	`http://www.contoso.com`	`x-ms-blob-content-type`	Aturan kedua	Berhasil
GET	`http://www.contoso.com`	`x-ms-client-request-id`	Aturan kedua	Kegagalan

Permintaan pertama cocok dengan aturan pertama – domain asal cocok dengan asal yang diizinkan, metode cocok dengan metode yang diizinkan, dan header cocok dengan header yang diizinkan - sehingga berhasil.

Permintaan kedua tidak cocok dengan aturan pertama karena metode tidak cocok dengan metode yang diizinkan. Namun, ini cocok dengan aturan kedua, sehingga berhasil.

Permintaan ketiga cocok dengan aturan kedua di domain dan metode asalnya, sehingga tidak ada aturan lebih lanjut yang dievaluasi. Namun, x-ms-client-request-id header tidak diizinkan oleh aturan kedua, sehingga permintaan gagal, terlepas dari kenyataan bahwa semantik aturan ketiga akan memungkinkannya untuk berhasil.

Catatan

Meskipun contoh ini menunjukkan aturan yang kurang ketat sebelum aturan yang lebih ketat, secara umum praktik terbaik adalah mencantumkan aturan yang paling ketat terlebih dahulu.

Memahami bagaimana header Vary diatur

Header Vary adalah header HTTP/1.1 standar yang terdiri dari sekumpulan bidang header permintaan yang menyarankan browser atau agen pengguna tentang kriteria yang dipilih oleh server untuk memproses permintaan. Header Vary ini terutama digunakan untuk penembolokan oleh proksi, browser, dan CDN, yang menggunakannya untuk menentukan bagaimana respons harus di-cache. Untuk detailnya, lihat spesifikasi untuk header Vary.

Ketika browser atau agen pengguna lain menyimpan respons dari permintaan CORS, domain asal di-cache sebagai asal yang diizinkan. Ketika domain kedua mengeluarkan permintaan yang sama untuk sumber daya penyimpanan saat cache aktif, agen pengguna mengambil domain asal yang di-cache. Domain kedua tidak cocok dengan domain yang di-cache, sehingga permintaan gagal ketika akan berhasil. Dalam kasus tertentu, Azure Storage mengatur header ke Origin untuk menginstruksikan Vary agen pengguna untuk mengirim permintaan CORS berikutnya ke layanan ketika domain yang meminta berbeda dari asal cache.

Azure Storage mengatur Vary header ke Origin untuk permintaan GET/HEAD aktual dalam kasus berikut:

Ketika asal permintaan sama persis dengan asal yang diizinkan yang ditentukan oleh aturan CORS. Agar sama persis, aturan CORS mungkin tidak menyertakan karakter kartubebas '*'.
Tidak ada aturan yang cocok dengan asal permintaan, tetapi CORS diaktifkan untuk layanan penyimpanan.

Dalam kasus di mana permintaan GET/HEAD cocok dengan aturan CORS yang memungkinkan semua asal, respons menunjukkan bahwa semua asal diizinkan, dan cache agen pengguna akan memungkinkan permintaan berikutnya dari domain asal mana pun saat cache aktif.

Perhatikan bahwa untuk permintaan yang menggunakan metode selain GET/HEAD, layanan penyimpanan tidak akan mengatur Vary header, karena respons terhadap metode ini tidak di-cache oleh agen pengguna.

Tabel berikut menunjukkan bagaimana penyimpanan Azure akan merespons permintaan GET/HEAD berdasarkan kasus yang disebutkan sebelumnya:

Header asal ada berdasarkan permintaan	Aturan CORS yang ditentukan untuk layanan ini	*Ada aturan yang cocok yang memungkinkan semua asal ()**	Aturan pencocokan ada untuk kecocokan asal yang tepat	Respons mencakup Vary header set ke Origin	*Respons mencakup Access-Control-Allowed-Origin: ""**	Respons mencakup Access-Control-Exposed-Headers
Tidak	Tidak	Tidak	Tidak	Tidak	Tidak	Tidak
Tidak	Ya	Tidak	Tidak	Ya	Tidak	Tidak
Tidak	Ya	Ya	Tidak	Tidak	Ya	Ya
Ya	Tidak	Tidak	Tidak	Tidak	Tidak	Tidak
Ya	Ya	Tidak	Ya	Ya	Tidak	Ya
Ya	Ya	Tidak	Tidak	Ya	Tidak	Tidak
Ya	Ya	Ya	Tidak	Tidak	Ya	Ya

Penagihan untuk permintaan CORS

Permintaan preflight yang berhasil ditagih jika Anda telah mengaktifkan CORS untuk salah satu layanan penyimpanan untuk akun Anda (dengan memanggil Set Blob Service Properties, Set Queue Service Properties, Set File Service Properties, atau Set Table Service Properties). Untuk meminimalkan biaya, pertimbangkan untuk mengatur MaxAgeInSeconds elemen dalam aturan CORS Anda ke nilai besar sehingga agen pengguna menyimpan permintaan.

Permintaan preflight yang gagal tidak akan ditagih.

Lihat juga

Spesifikasi Berbagi Sumber Daya Lintas Asal W3C