Menambahkan dukungan CORS ke proxy API

Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi Apigee X. info

CORS (Cross-origin resource sharing) adalah mekanisme standar yang memungkinkan panggilan JavaScript XMLHttpRequest (XHR) yang dieksekusi di halaman web berinteraksi dengan resource dari domain lintas origin. CORS adalah solusi yang umum diterapkan untuk "kebijakan origin yang sama" yang diterapkan oleh semua browser. Misalnya, jika Anda membuat panggilan XHR ke Twitter API dari kode JavaScript yang dieksekusi di browser, panggilan akan gagal. Hal ini karena domain yang menayangkan halaman ke browser Anda tidak sama dengan domain yang menayangkan Twitter API. CORS memberikan solusi untuk masalah ini dengan mengizinkan server untuk "ikut serta" jika ingin menyediakan berbagi resource lintas origin.

Video: Tonton video pendek untuk mempelajari cara mengaktifkan CORS di Proxy API.

Kasus penggunaan umum untuk CORS

Kode JQuery berikut memanggil layanan target fiktif. Jika dieksekusi dari dalam konteks browser (halaman web), panggilan akan gagal karena kebijakan origin yang sama:

<script>
var url = "http://service.example.com";
$(document).ready(function(){
  $("button").click(function(){
    $.ajax({
        type:"GET",
        url:url,
        async:true,
        dataType: "json",
           success: function(json) {
              // Parse the response.
              // Do other things.
           },
           error: function(xhr, status, err) {
              // This is where we end up!
            }
    });
  });
});
</script>

Salah satu solusi untuk masalah ini adalah membuat proxy Apigee API yang memanggil API layanan di backend. Ingatlah bahwa Edge berada di antara klien (browser dalam kasus ini) dan API backend (layanan). Karena proxy API dieksekusi di server, bukan di browser, dapat memanggil layanan dengan berhasil. Kemudian, Anda hanya perlu melampirkan header CORS ke respons TargetEndpoint. Selama browser mendukung CORS, header ini memberi sinyal kepada browser bahwa tidak apa-apa untuk "mengurangi" kebijakan origin yang sama, sehingga panggilan API lintas origin berhasil.

Setelah proxy dengan dukungan CORS dibuat, Anda dapat memanggil URL proxy API, bukan layanan backend dalam kode sisi klien Anda. Contoh:

<script>
var url = "http://myorg-test.apigee.net/v1/example";
$(document).ready(function(){
  $("button").click(function(){
    $.ajax({
        type:"GET",
        url:url,
        async:true,
        dataType: "json",
           success: function(json) {
              // Parse the response.
              // Do other things.
           },
           error: function(xhr, status, err) {
              // This time, we do not end up here!
            }
    });
  });
});
</script>

Melampirkan kebijakan Tambahkan CORS ke proxy API baru

Anda dapat menambahkan dukungan CORS ke proxy API dengan melampirkan kebijakan "Tambahkan CORS" ke proxy API saat Anda membuatnya. Untuk menambahkan kebijakan ini, centang kotak Tambahkan header CORS di halaman Keamanan pada wizard Buat Proxy.

Saat Anda mencentang kotak ini, kebijakan bernama Add CORS akan otomatis ditambahkan ke sistem dan dilampirkan ke preflow respons TargetEndpoint, seperti yang ditunjukkan pada gambar berikut:

Kebijakan CORS ditambahkan ke navigator di bagian Kebijakan dan dilampirkan ke preflow respons TargetEndpoint di panel kanan

Kebijakan Add CORS diimplementasikan sebagai kebijakan AssignMessage, yang menambahkan header yang sesuai ke respons. Pada dasarnya, header memberi tahu browser asal mana yang akan berbagi resource-nya, metode mana yang diterima, dan sebagainya. Anda dapat membaca lebih lanjut header CORS ini di Rekomendasi W3C untuk Cross-Origin Resource Sharing.

Anda harus mengubah kebijakan, sebagai berikut:

  • Tambahkan header content-type dan authorization (diperlukan untuk mendukung autentikasi dasar atau OAuth2) ke header Access-Control-Allow-Headers, seperti yang ditunjukkan dalam cuplikan kode di bawah.
  • Untuk autentikasi OAuth2, Anda mungkin perlu melakukan langkah-langkah untuk memperbaiki perilaku yang tidak sesuai dengan RFC.
  • Sebaiknya gunakan <Set> untuk menyetel header CORS, bukan <Add>, seperti yang ditunjukkan dalam kutipan di bawah. Saat menggunakan <Add>, jika header Access-Control-Allow-Origin sudah ada, Anda akan menerima error berikut:

    The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.

    Untuk mengetahui informasi selengkapnya, lihat Error CORS : header berisi beberapa nilai '*, *', tetapi hanya satu yang diizinkan.

<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Menambahkan header CORS ke proxy yang ada

Anda harus membuat kebijakan Assign Message baru secara manual dan menyalin kode untuk kebijakan Add CORS yang tercantum di bagian sebelumnya ke dalamnya. Kemudian, lampirkan kebijakan ke preflow respons TargetEndpoint proxy API. Anda dapat mengubah nilai header sesuai kebutuhan. Untuk mengetahui informasi selengkapnya tentang cara membuat dan melampirkan kebijakan, lihat Apa itu kebijakan?.

Menangani permintaan preflight CORS

Preflight CORS mengacu pada pengiriman permintaan ke server untuk memverifikasi apakah server tersebut mendukung CORS. Respons preflight umum mencakup asal yang akan diterima server untuk permintaan CORS, daftar metode HTTP yang didukung untuk permintaan CORS, header yang dapat digunakan sebagai bagian dari permintaan resource, waktu maksimum respons preflight akan di-cache, dan lainnya. Jika layanan tidak menunjukkan dukungan CORS atau tidak ingin menerima permintaan lintas origin dari origin klien, kebijakan lintas origin browser akan diterapkan dan semua permintaan lintas domain yang dibuat dari klien untuk berinteraksi dengan resource yang dihosting di server tersebut akan gagal.

Biasanya, permintaan preflight CORS dibuat dengan metode HTTP OPTIONS. Saat server yang mendukung CORS menerima permintaan OPTIONS, server akan menampilkan serangkaian header CORS ke klien yang menunjukkan tingkat dukungan CORS-nya. Sebagai hasil dari handshake ini, klien mengetahui apa yang diizinkan untuk diminta dari domain non-asal.

Untuk mengetahui informasi selengkapnya tentang pra-penerbangan, lihat Rekomendasi W3C untuk Cross-Origin Resource Sharing. Selain itu, ada banyak blog dan artikel tentang CORS yang dapat Anda baca.

Apigee tidak menyertakan solusi preflight CORS secara langsung, tetapi solusi ini dapat diimplementasikan, seperti yang dijelaskan di bagian ini. Tujuannya adalah agar proxy mengevaluasi permintaan OPTIONS dalam alur bersyarat. Proxy kemudian dapat mengirimkan respons yang sesuai kembali ke klien.

Mari kita lihat contoh alur, lalu bahas bagian yang menangani permintaan pra-penerbangan:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
    <Description/>
    <Flows>
        <Flow name="OptionsPreFlight">
            <Request/>
            <Response>
                <Step>
                    <Name>add-cors</Name>
                </Step>
            </Response>
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
        </Flow>
    </Flows>

    <PreFlow name="PreFlow">
        <Request/>
        <Response/>

    </PreFlow>
    <HTTPProxyConnection>
        <BasePath>/v1/cnc</BasePath>
        <VirtualHost>default</VirtualHost>
        <VirtualHost>secure</VirtualHost>
    </HTTPProxyConnection>
    <RouteRule name="NoRoute">
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
    </RouteRule>
    <RouteRule name="default">
        <TargetEndpoint>default</TargetEndpoint>
   </RouteRule>
   <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
</ProxyEndpoint>

Bagian utama ProxyEndpoint ini adalah sebagai berikut:

  • RouteRule dibuat ke target NULL dengan kondisi untuk permintaan OPTIONS. Perhatikan bahwa tidak ada TargetEndpoint yang ditentukan. Jika permintaan OPTIONS diterima dan header permintaan Origin dan Access-Control-Request-Method tidak null, proxy akan segera menampilkan header CORS dalam respons kepada klien (melewati target "backend" default yang sebenarnya). Untuk mengetahui detail tentang kondisi alur dan RouteRule, lihat Kondisi dengan variabel alur.

    <RouteRule name="NoRoute">
    <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
</RouteRule>
  • Alur OptionsPreFlight dibuat yang menambahkan kebijakan CORS Add, yang berisi header CORS, ke alur jika permintaan OPTIONS diterima dan header permintaan Origin dan Access-Control-Request-Method tidak null. 

     <Flow name="OptionsPreFlight">
            <Request/>
            <Response>
                <Step>
                    <Name>add-cors</Name>
                </Step>
            </Response>
        <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
 </Flow>

Menggunakan solusi CORS contoh

Contoh solusi CORS, yang diterapkan sebagai alur bersama, tersedia di GitHub. Impor paket alur bersama ke lingkungan Anda dan lampirkan menggunakan flow hook atau langsung ke alur proxy API. Untuk mengetahui detailnya, lihat file README CORS-Shared-Flow yang disertakan dengan contoh.