CORS

  • Artikel

BERLAKU UNTUK: Semua tingkatAN API Management

Kebijakan cors menambahkan dukungan berbagi sumber daya lintas asal (CORS) ke operasi atau API untuk memungkinkan panggilan lintas domain dari klien berbasis browser.

Catatan

Tetapkan elemen kebijakan dan elemen turunan dalam urutan yang disediakan dalam pernyataan kebijakan. Untuk membantu Anda mengonfigurasi kebijakan ini, portal menyediakan editor berbasis formulir berikut panduannya. Pelajari lebih lanjut cara mengatur atau mengedit kebijakan API Management.

Pernyataan kebijakan

<cors allow-credentials="false | true" terminate-unmatched-request="true | false">
    <allowed-origins>
        <origin>origin uri</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="number of seconds">
        <method>HTTP verb</method>
    </allowed-methods>
    <allowed-headers>
        <header>header name</header>
    </allowed-headers>
    <expose-headers>
        <header>header name</header>
    </expose-headers>
</cors>

Atribut

Nama Deskripsi Wajib diisi Default
allow-credentials Header Access-Control-Allow-Credentials dalam respons pra-penerbangan akan diatur ke nilai atribut ini dan mempengaruhi kemampuan klien untuk mengirimkan kredensial dalam permintaan lintas domain. Ekspresi kebijakan diizinkan. No false
terminate-unmatched-request Mengontrol pemrosesan permintaan lintas asal yang tidak cocok dengan pengaturan kebijakan. Ekspresi kebijakan diizinkan.

Ketika OPTIONS permintaan diproses sebagai permintaan preflight dan Origin header tidak cocok dengan pengaturan kebijakan:
- Jika atribut diatur ke true, segera hentikan permintaan dengan respons kosong 200 OK
- Jika atribut diatur ke false, periksa masuk untuk kebijakan dalam cakupan cors lain yang merupakan turunan langsung dari elemen masuk dan terapkan. Jika tidak ada kebijakan cors yang ditemukan, hentikan permintaan dengan respons 200 OK kosong.

Ketika GET atau HEAD permintaan menyertakan Origin header (dan oleh karena itu diproses sebagai permintaan lintas asal sederhana), dan tidak cocok dengan pengaturan kebijakan:
- Jika atribut diatur ke true, segera hentikan permintaan dengan respons kosong 200 OK .
- Jika atribut diatur ke false, izinkan permintaan untuk dilanjutkan secara normal dan jangan tambahkan header CORS ke respons.		 No true

Elemen

Nama Deskripsi Wajib diisi Default
allowed-origins Berisi elemen origin yang menjelaskan asal yang diizinkan untuk permintaan lintas domain. allowed-origins dapat berisi satu elemen origin yang menentukan * untuk memungkinkan asal mana pun, atau satu atau lebih elemen origin yang berisi URI. Ya T/A
allowed-methods Elemen ini diperlukan jika metode selain GET atau POST diizinkan. Berisi elemen method yang menentukan kata kerja HTTP yang didukung. Nilai * menunjukkan semua metode. No Jika bagian ini tidak ada, GET dan POST didukung.
allowed-headers Elemen ini berisi elemen header yang menentukan nama header yang dapat disertakan dalam permintaan. Ya T/A
expose-headers Elemen ini berisi elemen header yang menentukan nama header yang akan dapat diakses oleh klien. No T/A

Perhatian

Gunakan wildcard * dengan hati-hati dalam pengaturan kebijakan. Konfigurasi ini mungkin terlalu permisif dan dapat membuat API lebih rentan terhadap Ancaman keamanan API tertentu.

elemen asal yang diizinkan

Nama Deskripsi Wajib diisi Default
asal Nilai dapat berupa * untuk memungkinkan semua asal, atau URI yang menentukan satu asal. URI harus menyertakan skema, host, dan port. Jangan sertakan tanda kutip. Ya Jika port dihilangkan dalam URI, port 80 digunakan untuk HTTP dan port 443 digunakan untuk HTTPS.

atribut metode yang diizinkan

Nama Deskripsi Wajib diisi Default
preflight-result-max-age Header Access-Control-Max-Age dalam respons preflight akan diatur ke nilai atribut ini dan memengaruhi kemampuan agen pengguna untuk membuat cache respons preflight. Ekspresi kebijakan diizinkan. No 0

elemen metode yang diizinkan

Nama Deskripsi Wajib diisi Default
metode Menentukan kata kerja HTTP. Ekspresi kebijakan diizinkan. Setidaknya satu elemen method diperlukan jika bagian allowed-methods tersebut ada. T/A

elemen allowed-headers

Nama Deskripsi Wajib diisi Default
{i>header Menentukan nama header. Setidaknya satu header elemen diperlukan jika allowed-headers bagian tersebut ada. T/A

elemen expose-headers

Nama Deskripsi Wajib diisi Default
{i>header Menentukan nama header. Setidaknya satu header elemen diperlukan jika expose-headers bagian tersebut ada. T/A

Penggunaan

Catatan penggunaan

  • Anda dapat mengonfigurasi kebijakan cors di lebih dari satu cakupan (misalnya, pada cakupan produk dan cakupan global). Pastikan elemen base dikonfigurasi pada operasi, API, dan cakupan produk untuk mewarisi kebijakan yang diperlukan pada cakupan induk.
  • Hanya kebijakan cors yang dievaluasi pada permintaan OPTIONS selama preflight. Kebijakan yang dikonfigurasi lainnya dievaluasi pada permintaan yang disetujui.
  • Kebijakan ini hanya dapat digunakan sekali di bagian kebijakan.

Tentang CORS

CORS adalah standar berbasis header HTTP yang memungkinkan browser dan server untuk berinteraksi dan menentukan apakah akan mengizinkan permintaan lintas asal tertentu (panggilan XMLHttpRequest yang dilakukan dari JavaScript di halaman web ke domain lain). Ini memungkinkan lebih banyak fleksibilitas daripada hanya memungkinkan permintaan asal yang sama, tetapi lebih aman daripada mengizinkan semua permintaan lintas asal.

CORS menentukan dua jenis permintaan lintas asal:

  • Permintaan yang telah di-preflight (atau "preflight") - Browser terlebih dahulu mengirim permintaan menggunakan metode OPTIONS ke server, untuk menentukan apakah permintaan aktual diizinkan untuk dikirim. Jika respons server menyertakan header Access-Control-Allow-Origin yang memungkinkan akses, browser mengikuti permintaan aktual.

  • Permintaan sederhana - Permintaan ini mencakup satu atau beberapa header Origin tambahan tetapi tidak memicu preflight CORS. Hanya permintaan yang menggunakan metode GET dan HEAD serta set header permintaan terbatas yang diizinkan.

skenario kebijakan cors

Konfigurasikan kebijakan cors di API Management untuk skenario berikut:

  • Aktifkan konsol pengujian interaktif di portal pengembang. Lihat dokumentasi portal pengembang untuk detailnya.

    Catatan

    Saat Anda mengaktifkan CORS untuk konsol interaktif, secara default API Management mengonfigurasi kebijakan cors di cakupan global.

  • Aktifkan API Management untuk membalas permintaan preflight atau untuk melewati permintaan CORS sederhana saat backend tidak menyediakan dukungan CORS mereka sendiri.

    Catatan

    Jika permintaan cocok dengan operasi dengan metode OPTIONS yang ditentukan dalam API, logika pemrosesan permintaan preflight yang terkait dengan kebijakan cors tidak akan dijalankan. Oleh karena itu, operasi tersebut dapat digunakan untuk menerapkan logika pemrosesan preflight kustom - misalnya, untuk menerapkan kebijakan cors hanya dalam kondisi tertentu.

Masalah konfigurasi umum

  • Kunci langganan di header - Jika Anda mengonfigurasi kebijakan cors di cakupan produk, dan API Anda menggunakan autentikasi kunci langganan, kebijakan tidak akan berfungsi saat kunci langganan diteruskan di header. Sebagai solusinya, ubah permintaan untuk menyertakan kunci langganan sebagai parameter kueri.
  • API dengan versi header - Jika Anda mengonfigurasi kebijakan cors di cakupan API, dan API Anda menggunakan skema versi header, kebijakan tidak akan berfungsi karena versi diteruskan di header. Anda mungkin perlu mengonfigurasi metode penerapan versi alternatif seperti jalur atau parameter kueri.
  • Urutan kebijakan - Anda mungkin mengalami perilaku tak terduga jika kebijakan cors tersebut bukan kebijakan pertama di bagian masuk. Pilih Hitung kebijakan efektif di editor kebijakan untuk memeriksa urutan evaluasi kebijakan di setiap cakupan. Umumnya, hanya kebijakan cors pertama yang diterapkan.
  • Respons Kosong 200 OK - Dalam beberapa konfigurasi kebijakan, permintaan lintas asal tertentu selesai dengan respons 200 OK kosong. Respons ini diharapkan ketika terminate-unmatched-request diatur ke nilai true defaultnya dan permintaan masuk memiliki header Origin yang tidak cocok dengan asal yang diizinkan yang dikonfigurasi dalam kebijakan cors.

Contoh

Contoh ini menunjukkan cara mendukung permintaan preflight, seperti permintaan dengan header kustom atau metode selain GET dan POST. Untuk mendukung header kustom dan kata kerja HTTP tambahan, gunakan bagian allowed-methods dan allowed-headers seperti yang diperlihatkan dalam contoh berikut.

<cors allow-credentials="true">
    <allowed-origins>
        <!-- Localhost useful for development -->
        <origin>http://localhost:8080/</origin>
        <origin>http://example.com/</origin>
    </allowed-origins>
    <allowed-methods preflight-result-max-age="300">
        <method>GET</method>
        <method>POST</method>
        <method>PATCH</method>
        <method>DELETE</method>
    </allowed-methods>
    <allowed-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
        <header>x-zumo-version</header>
        <header>x-zumo-auth</header>
        <header>content-type</header>
        <header>accept</header>
    </allowed-headers>
    <expose-headers>
        <!-- Examples below show Azure Mobile Services headers -->
        <header>x-zumo-installation-id</header>
        <header>x-zumo-application</header>
    </expose-headers>
</cors>

Konten terkait

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat: