Menambahkan dukungan CORS ke proxy API

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Peringatan: Contoh yang diberikan di bagian ini memungkinkan akses ke proxy API Anda dari asal mana pun dan harus diamankan sebelum digunakan di lingkungan produksi. Misalnya, Anda dapat mengizinkan domain yang dapat mengakses proxy API.

CORS (Cross-origin resource sharing) adalah mekanisme standar yang memungkinkan panggilan XMLHttpRequest (XHR) JavaScript yang dijalankan di halaman web untuk berinteraksi dengan resource dari domain non-asal. CORS adalah solusi yang umum diterapkan untuk kebijakan origin yang sama yang diterapkan oleh semua browser. Misalnya, jika Anda melakukan panggilan XHR ke Twitter API dari kode JavaScript yang dijalankan 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.

Catatan: Sebagian besar browser modern mendukung CORS. Lihat Cross-Origin Resource Sharing untuk melihat daftar lengkap browser yang didukung. Untuk deskripsi mendalam tentang CORS, lihat Fetch Living Standard.

Jika menggunakan kebijakan cache di proxy API, Anda harus memastikan bahwa respons kebijakan CORS tidak disimpan dalam cache.

Kasus penggunaan umum untuk CORS

Kode JQuery berikut memanggil layanan target fiktif. Jika dijalankan 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 API Apigee yang memanggil API layanan di backend. Ingat bahwa Apigee berada di antara klien (browser dalam hal ini) dan API backend (layanan). Karena proxy API dijalankan di server, bukan di browser, proxy tersebut dapat berhasil memanggil layanan. Kemudian, yang perlu Anda lakukan adalah melampirkan header CORS ke respons TargetEndpoint. Selama browser mendukung CORS, header ini akan memberi sinyal ke browser bahwa kebijakan asal yang sama dapat dilonggarkan, sehingga panggilan API lintas origin dapat berhasil.

Setelah proxy dengan dukungan CORS dibuat, Anda dapat memanggil URL proxy API, bukan layanan backend dalam kode sisi klien. 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>

Catatan: Dalam kasus paling sederhana, Anda dapat menampilkan header CORS ke klien dan permintaan lintas-asal akan berfungsi. Ada kasus yang lebih rumit saat permintaan preflight diperlukan. Anda dapat membaca tentang permintaan CORS preflight di Fetch Living Standard, serta di berbagai artikel dan blog. Lihat juga Menangani permintaan preflight CORS di bawah.

Melampirkan kebijakan CORS ke PreFlow permintaan ProxyEndpoint

Melampirkan kebijakan Tambahkan CORS ke proxy API baru

Anda dapat menambahkan dukungan CORS ke proxy API dengan melampirkan kebijakan Add CORS ke proxy API dengan cara berikut:

• Saat Anda membuat kebijakan dengan memilih kotak centang Tambahkan header CORS di halaman Keamanan pada wizard Buat Proxy
• Dengan menambahkannya nanti dari dialog Tambahkan Kebijakan

Saat Anda menambahkan kebijakan CORS dengan mencentang kotak, kebijakan yang disebut Add CORS akan otomatis ditambahkan ke sistem dan dilampirkan ke preflow permintaan TargetEndpoint.

Kebijakan Tambahkan CORS menambahkan header yang sesuai ke respons. Pada dasarnya, header memungkinkan browser mengetahui asal yang akan berbagi resource, metode yang diterima, dan sebagainya. Anda dapat membaca selengkapnya tentang header CORS ini di Rekomendasi W3C 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 mengambil langkah-langkah untuk memperbaiki perilaku yang tidak mematuhi RFC.

<CORS continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <AllowOrigins>{request.header.origin}</AllowOrigins>
    <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
    <AllowHeaders>origin, x-requested-with, accept, content-type, authorization</AllowHeaders>
    <ExposeHeaders>*</ExposeHeaders>
    <MaxAge>3628800</MaxAge>
    <AllowCredentials>false</AllowCredentials>
    <GeneratePreflightResponse>true</GeneratePreflightResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

Menambahkan header CORS ke proxy yang ada

Catatan: Apigee memperkenalkan Editor Proxy versi baru, yang akan mempermudah pengelolaan proxy.

Petunjuk di dua tab pertama di bawah menjelaskan cara menggunakan Editor Proxy baru atau Editor Proxy klasik.

Editor Proxy Baru

Untuk menambahkan kebijakan CORS ke proxy API yang ada:

1. Jika Anda menggunakan UI Apigee di konsol Cloud: Pilih Proxy development > API Proxies.

   Jika Anda menggunakan UI Apigee klasik: Pilih Develop > API Proxies dan di panel Proxies, pilih lingkungan untuk proxy.

2. Pilih proxy API tempat Anda ingin menambahkan kebijakan CORS.
3. Di editor untuk proxy API baru, klik tab Develop.
4. Di panel kiri, klik tombol + di baris Policies.

5. Pada dialog Create policy, klik kolom Select policy type, lalu scroll ke bawah ke Security dan pilih CORS.

6. Masukkan detail untuk kebijakan, lalu klik Buat.

7. Di panel kiri, klik PreFlow di bagian Target Endpoints > default.
8. Klik tombol + di samping PreFlow di panel Request di kanan bawah Visual Editor.
9. Di dialog Langkah menambahkan kebijakan, pilih kebijakan CORS.

10. Klik Tambahkan untuk melampirkan kebijakan.

Editor Proxy Klasik

Untuk menambahkan kebijakan CORS ke proxy API yang ada:

1. Login ke UI Apigee.
2. Pilih Develop > API Proxies di menu navigasi sebelah kiri.
Jika Anda melihat tombol Coba sekarang, klik tombol tersebut untuk menampilkan tampilan Develop yang baru.

Tentang tombol Coba sekarang

Jika ini pertama kalinya Anda menggunakan Proxy Editor versi baru, Anda akan melihat banner berikut di bagian atas tampilan Develop:



Klik tombol Coba sekarang untuk menampilkan tampilan Develop baru.

Catatan: Jika sebelumnya Anda mengklik tombol Coba sekarang, tombol tersebut tidak akan ditampilkan.

Tampilan Develop ditampilkan di bawah.



3. Pilih proxy API tempat Anda ingin menambahkan kebijakan CORS.
4. Di editor untuk proxy API baru, klik tab Develop:

5. Di panel Navigator sebelah kiri, klik PreFlow di bagian Target Endpoints > default.
6. Klik tombol +Langkah di bagian atas, yang sesuai dengan Pra-Alur Permintaan. Tindakan ini akan menampilkan daftar yang dikategorikan dari semua kebijakan yang dapat Anda buat.
   
7. Pilih CORS di kategori Security.
8. Berikan nama, seperti Add CORS, lalu klik Tambahkan.

Menangani permintaan preflight CORS

Preflight CORS mengacu pada pengiriman permintaan ke server untuk memverifikasi apakah server tersebut mendukung CORS. Respons preflight standar mencakup asal server yang akan menerima 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 permintaan lintas-domain apa pun yang dibuat dari klien untuk berinteraksi dengan resource yang dihosting di server tersebut akan gagal.

Biasanya, permintaan preflight CORS dibuat dengan metode OPTIONS HTTP. Saat server yang mendukung CORS menerima permintaan OPTIONS, server akan menampilkan kumpulan 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.

Catatan: Jika Anda memiliki kebijakan Verifikasi kunci API di PreFlow endpoint proxy, kebijakan tersebut akan diterapkan ke semua permintaan yang masuk. Jika Anda tidak ingin menerapkan kebijakan untuk permintaan pra-penerbangan CORS, tambahkan kondisi untuk melewati jika metodenya adalah OPTIONS. Misalnya, gunakan konfigurasi proxy API berikut:

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Name>verify-api-key</Name>
            <Condition>request.verb != "OPTIONS"</Condition>
        </Step>
    </Request>
    <Response/>
</PreFlow>

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

Apigee tidak menyertakan solusi pra-penerbangan CORS secara default, tetapi dapat diimplementasikan, seperti yang dijelaskan di bagian ini. Tujuannya adalah agar proxy mengevaluasi permintaan OPTIONS dalam alur kondisional. Proxy kemudian dapat mengirim 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>
                <Step>
                    <Name>add-cors</Name>
                </Step>
            </Request>
            <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 ke klien (mengabaikan 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 Tambahkan CORS, 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>
                  <Step>
                      <Name>add-cors</Name>
                  </Step>
              </Request>
              <Response/>
          <Condition>request.verb == "OPTIONS" AND request.header.origin != null AND request.header.Access-Control-Request-Method != null</Condition>
   </Flow>

Catatan: RouteRules dievaluasi dalam urutan yang ditentukan dalam konfigurasi ProxyEndpoint. Anda harus selalu memiliki Rute default (tanpa kondisi) di bagian akhir. Jika tidak, jika berada di bagian atas, Route akan selalu cocok dan tidak pernah mengevaluasi kemungkinan Route lainnya.