Kebijakan CORS

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Apa

Cross-origin resource sharing (CORS) adalah mekanisme standar yang memungkinkan panggilan JavaScript XMLHttpRequest (XHR) yang dieksekusi di halaman web 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 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 cross-origin resource sharing.

Kebijakan CORS ini memungkinkan pelanggan Apigee menetapkan kebijakan CORS untuk API yang digunakan oleh aplikasi web.

Kebijakan ini adalah kebijakan Standar dan dapat di-deploy ke jenis lingkungan apa pun. Untuk mengetahui informasi tentang jenis dan ketersediaan kebijakan dengan setiap jenis lingkungan, lihat Jenis kebijakan.

Perhatian:

Menerapkan kebijakan CORS dapat melonggarkan kebijakan origin yang sama (SOP). Jika developer proxy menetapkan header Access-Control-Allow-Origin untuk mengizinkan semua (*), tindakan ini secara efektif menonaktifkan perlindungan origin yang sama.

Kolom AllowOrigins adalah elemen kebijakan yang wajib ada dan defaultnya tidak boleh disetel untuk mengizinkan semua (*). Developer kebijakan harus membuat keputusan yang hati-hati sebelum mengekspos resource mereka.

Kasus penggunaan

Salah satu kasus penggunaan umum CORS adalah fitur Coba API iniSmartDoc di portal developer.

Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi proxy API untuk mendukung panel Coba API ini.

Elemen <CORS>

Menentukan kebijakan CORS.

Nilai Default	Lihat tab Kebijakan Default di bawah
Wajib?	Wajib
Jenis	Objek kompleks
Elemen Induk	T/A
Elemen Turunan	<AllowCredentials> <AllowHeaders> <AllowMethods> <AllowOrigins> <DisplayName> <ExposeHeaders> <GeneratePreflightResponse> <IgnoreUnresolvedVariables> <MaxAge>

Elemen <CORS> menggunakan sintaksis berikut:

Sintaks

Elemen <CORS> menggunakan sintaksis berikut:

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <DisplayName>DISPLAY_NAME</DisplayName>
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
  <MaxAge>[integer|-1]</MaxAge>
  <AllowCredentials>[false|true]</AllowCredentials>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

Kebijakan default

Contoh berikut menunjukkan setelan default saat Anda menambahkan kebijakan CORS ke alur di UI Edge:

<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</AllowHeaders>
    <ExposeHeaders>*</ExposeHeaders>
    <MaxAge>3628800</MaxAge>
    <AllowCredentials>false</AllowCredentials>
    <GeneratePreflightResponse>true</GeneratePreflightResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

Saat Anda menyisipkan kebijakan CORS baru di UI Apigee, template akan berisi stub untuk semua kemungkinan operasi. Biasanya, Anda memilih operasi yang ingin dilakukan dengan kebijakan ini dan menghapus elemen turunan lainnya. Misalnya, jika Anda ingin menentukan metode HTTP yang diizinkan untuk mengakses resource, gunakan elemen <AllowMethods> dan hapus elemen turunan lainnya dari kebijakan agar lebih mudah dibaca.

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
name	N/A	Required	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError	false	Optional	Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
enabled	true	Optional	Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async	false	Deprecated	This attribute is deprecated.

Setiap elemen turunan dijelaskan di bagian selanjutnya.

Contoh

Contoh disediakan untuk semua elemen turunan di bagian berikut.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan <CORS>.

<AllowCredentials>

Menunjukkan apakah pemanggil diizinkan untuk mengirim permintaan sebenarnya (bukan preflight) menggunakan kredensial. Diterjemahkan ke header Access-Control-Allow-Credentials.

Nilai Default	Jika tidak ditentukan, Access-Control-Allow-Credentials tidak akan ditetapkan.
Wajib?	Opsional
Jenis	Boolean
Elemen Induk	<CORS>
Elemen Turunan	Tidak ada

Elemen <AllowCredentials> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowCredentials>[false|true]</AllowCredentials>
</CORS>
      

Contoh

This example sets the Access-Control-Allow-Credentials header to false. That is, the caller is not allowed to send the actual request (not the preflight) using credentials.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowCredentials>false</AllowCredentials>
</CORS>

<AllowHeaders>

Daftar header HTTP yang dapat digunakan saat meminta resource. Diserialisasi ke header Access-Control-Allow-Headers.

Nilai Default	Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers
Wajib?	Opsional
Jenis	String, dengan dukungan template pesan*
Elemen Induk	<CORS>
Elemen Turunan	Tidak ada

Tips: Apigee merekomendasikan untuk menambahkan tidak lebih dari 50 nilai ke <AllowHeaders>.

* Untuk mengetahui informasi selengkapnya, lihat Apa itu template pesan?

Elemen <AllowHeaders> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowHeaders>[origin, x-requested-with, accept, content-type, ...]</AllowHeaders>
</CORS>

Contoh

This example specifies the HTTP headers that can be used when requesting the resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowHeaders>origin, x-requested-with, accept, content-type</AllowHeaders>
</CORS>

<AllowMethods>

Daftar metode HTTP yang diizinkan untuk mengakses resource. Konten akan diserialkan ke dalam header Access-Control-Allow-Methods.

Nilai Default	GET, POST, HEAD, OPTIONS
Wajib?	Opsional
Jenis	String, dengan dukungan template pesan*
Elemen Induk	<CORS>
Elemen Turunan	Tidak ada

* Untuk mengetahui informasi selengkapnya, lihat Apa itu template pesan?

Elemen <AllowMethods> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <AllowMethods>[GET, PUT, POST, DELETE, ...|*]</AllowMethods>
</CORS>

Contoh:
List

This example specifies the HTTP methods that are allowed to access the resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>GET, PUT, POST, DELETE</AllowMethods>
</CORS>

Contoh:
Karakter pengganti

Contoh ini menentukan bahwa semua metode HTTP diizinkan untuk mengakses resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <AllowMethods>*</AllowMethods>
</CORS>

<AllowOrigins>

Daftar origin yang diizinkan untuk mengakses resource. Gunakan tanda bintang (*) untuk mengaktifkan akses ke resource dari asal mana pun. Jika tidak, berikan daftar yang diizinkan berisi asal yang dipisahkan koma. Jika kecocokan ditemukan, Access-Control-Allow-Origin keluar ditetapkan ke origin seperti yang diberikan oleh klien.

Nilai Default	T/A
Wajib?	Wajib
Jenis	String, dengan dukungan template pesan*
Elemen Induk	<CORS>
Elemen Turunan	Tidak ada

Tips: Apigee merekomendasikan untuk menambahkan tidak lebih dari 50 nilai ke <AllowOrigins>.

* Untuk mengetahui informasi selengkapnya, lihat Apa itu template pesan?

Elemen <AllowOrigins> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
</CORS>

Contoh:
URL Tunggal

This example specifies a single URL origin that is allowed to access the resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org</AllowOrigins>
</CORS>

Contoh:
Beberapa URL

Contoh ini menentukan beberapa origin yang diizinkan untuk mengakses resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>https://www.w3.org, https://www.apache.org</AllowOrigins>
</CORS>

Contoh:
Variabel konteks

This example specifies a context variable that represents one or more origins that are allowed to access the resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{origins.list}</AllowOrigins>
</CORS>

Contoh:
Variabel alur

This example specifies a flow variable that represents one origin that is allowed to access the resource.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
</CORS>

Contoh:
Karakter pengganti

This example specifies that all origins are allowed to access the resource.

Note: You can also set a context variable in a message template to an asterisk (*).

Caution: If a proxy developer sets the Access-Control-Allow-Origin header to allow all (*), it effectively disables the same-origin protection. The default should not be set to allow all (*). Policy developers should make cautious decisions before exposing their resources.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>*</AllowOrigins>
</CORS>

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type	String
Parent Element	<PolicyElement>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Example

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

The <DisplayName> element has no attributes or child elements.

<ExposeHeaders>

Daftar header HTTP yang diizinkan untuk diakses oleh browser atau tanda bintang (*) untuk mengizinkan semua header HTTP. Diserialkan ke dalam header Access-Control-Expose-Headers.

Nilai Default	Jika tidak ditentukan, Access-Control-Expose-Headers tidak akan ditetapkan. Header tidak sederhana tidak diekspos secara default.
Wajib?	Opsional
Jenis	String, dengan dukungan template pesan*
Elemen Induk	<CORS>
Elemen Turunan	Tidak ada

Tips: Apigee merekomendasikan untuk menambahkan tidak lebih dari 50 nilai ke <ExposeHeaders>.

* Untuk mengetahui informasi selengkapnya, lihat Apa itu template pesan?

Elemen <ExposeHeaders> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <ExposeHeaders>[X-CUSTOM-HEADER-A, X-CUSTOM-HEADER-B, ... | *]</ExposeHeaders>
</CORS>

Contoh

Contoh ini menentukan bahwa browser diizinkan untuk mengakses semua header HTTP.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <ExposeHeaders>*</ExposeHeaders>
</CORS>

<GeneratePreflightResponse>

Menunjukkan apakah kebijakan harus membuat dan menampilkan respons preflight CORS. Jika false, tidak ada respons yang dikirim. Sebagai gantinya, variabel alur berikut akan diisi:

• cross_origin_resource_sharing.allow.credentials
• cross_origin_resource_sharing.allow.headers
• cross_origin_resource_sharing.allow.methods
• cross_origin_resource_sharing.allow.origin
• cross_origin_resource_sharing.allow.origins.list
• cross_origin_resource_sharing.expose.headers
• cross_origin_resource_sharing.max.age
• cross_origin_resource_sharing.preflight.accepted
• cross_origin_resource_sharing.request.headers
• cross_origin_resource_sharing.request.method
• cross_origin_resource_sharing.request.origin
• cross_origin_resource_sharing.request.type

Nilai Default	true
Wajib?	Opsional
Jenis	Boolean
Elemen Induk	<CORS>
Elemen Turunan	Tidak ada

Elemen <GeneratePreflightResponse> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
  <GeneratePreflightResponse>[false|true]</GeneratePreflightResponse>
</CORS>

Contoh

Contoh ini menentukan bahwa kebijakan harus membuat dan menampilkan respons preflight CORS.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <GeneratePreflightResponse>true</GeneratePreflightResponse>
</CORS>

<IgnoreUnresolvedVariables>

Menentukan apakah pemrosesan berhenti saat variabel yang belum diselesaikan ditemukan. Setel ke true untuk mengabaikan variabel yang belum diselesaikan dan melanjutkan pemrosesan; jika tidak, false.

Nilai Default	true
Wajib?	Opsional
Jenis	Boolean
Elemen Induk	<CORS>
Elemen Turunan	Tidak ada

Elemen <IgnoreUnresolvedVariables> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</CORS>

Contoh

This example specifies that processing continues when an unresolved variable is encountered.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</CORS>

<MaxAge>

Menentukan berapa lama hasil permintaan preflight dapat di-cache dalam detik. Nilai -1 akan mengisi header Access-Control-Max-Age dengan nilai -1, yang menonaktifkan penyimpanan dalam cache, sehingga memerlukan pemeriksaan OPTIONS pra-penerbangan untuk semua panggilan. Hal ini ditentukan dalam spesifikasi Access-Control-Max-Age.

Nilai Default	1800
Wajib?	Opsional
Jenis	Bilangan bulat
Elemen Induk	<CORS>
Elemen Turunan	Tidak ada

Elemen <MaxAge> menggunakan sintaksis berikut:

Sintaks

<CORS continueOnError="[false|true]" enabled="[false|true]" name="POLICY_NAME">
  <AllowOrigins>[{message template}|URL|URL, URL, ...|{context-variable}|{flow-variable}|*]</AllowOrigins>
  <MaxAge>[integer|-1]</MaxAge>
</CORS>

Contoh:
Cache

This example specifies that the results of a preflight request can be cached for 3628800 seconds.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>3628800</MaxAge>
</CORS>

Contoh:
Tanpa cache

This example specifies that the results of a preflight request cannot be cached.

<CORS continueOnError="false" enabled="true" name="add-cors">
  <AllowOrigins>{request.header.origin}</AllowOrigins>
  <MaxAge>-1</MaxAge>
</CORS>

Catatan penggunaan

OPTIONS permintaan

Saat permintaan OPTIONS diterima dan diproses oleh kebijakan CORS, eksekusi alur proxy ditransfer langsung ke PreFlow Respons Proxy, melewati alur permintaan sepenuhnya dan melanjutkan eksekusi dari sana. Tidak perlu membuat Kondisi untuk mengabaikan permintaan OPTIONS dalam alur permintaan proxy.

Pada panggilan berikutnya, saat kebijakan CORS dijalankan, jika MaxAge yang ditetapkan dalam kebijakan belum berakhir, alur akan dilanjutkan seperti biasa. Selama alur respons akhir tepat sebelum "Response Sent to Client", langkah eksekusi CORS khusus "CORSResponseOrErrorFlowExecution" menetapkan header respons CORS (Access-Control-Allow-Credentials, Access-Control-Allow-Origin, dan Access-Control-Expose-Headers) untuk menampilkan respons yang divalidasi CORS.

Kode error

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
steps.cors.UnresolvedVariable	500	This error occurs if a variable specified in the CORS policy is either: Out of scope (not available in the specific flow where the policy is being executed) or Can't be resolved (is not defined)

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
InvalidMaxAge	MaxAge is not number
MissingAllowOrigins	AllowOrigins is not specified
InvalidHTTPMethods	One of the methods in AllowMethods is not valid
AllowHeadersSizeTooLarge	The string size in AllowHeaders is too large.
ExposeHeadersSizeTooLarge	The string size in ExposeHeaders is too large.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Note : If <GeneratePreflightResponse> is set to true and an error occurs, the policy returns a response to the client immediately and the error flow is skipped. The following variables are not populated:

Variables	Where	Example
fault.name = "FAULT_NAME"	FAULT_NAME is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "UnresolveVariable"
cors.POLICY_NAME.failed	POLICY_NAME is the user-specified name of the policy that threw the fault.	cors.AddCORS.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
   "fault":{
      "detail":{
         "errorcode":"steps.cors.UnresolvedVariable"
      },
      "faultstring":"CORS[AddCORS]: unable to resolve variable wrong.var"
   }
}

Example fault rule

<FaultRule name="Add CORS Fault">
    <Step>
        <Name>Add-CORSCustomUnresolvedVariableErrorResponse</Name>
        <Condition>(fault.name Matches "UnresolvedVariable") </Condition>
    </Step>
    <Condition>(cors.Add-CORS.failed = true) </Condition>
</FaultRule>

Variabel alur

Objek CorsFlowInfo FlowInfo akan ditambahkan dan akan tersedia untuk pelacakan.

Properti	Jenis	Baca/Tulis	Deskripsi	Cakupan dimulai
cross_origin_resource_sharing.allow.credentials	Boolean	Baca/Tulis	Nilai dari <AllowCredentials>	Permintaan proxy
cross_origin_resource_sharing.allow.headers	String	Baca/Tulis	Nilai dari <AllowHeaders>	Permintaan proxy
cross_origin_resource_sharing.allow.methods	String	Baca/Tulis	Nilai dari <AllowMethods>	Permintaan proxy
cross_origin_resource_sharing.allow.origin	String	Baca/Tulis	Asal permintaan yang diizinkan, kosong jika tidak ada dalam daftar yang diizinkan	Permintaan proxy
cross_origin_resource_sharing.allow.origins.list	String	Baca/Tulis	Nilai dari <AllowOrigins>	Permintaan proxy
cross_origin_resource_sharing.expose.headers	String	Baca/Tulis	Nilai dari <ExposeHeaders>	Permintaan proxy
cross_origin_resource_sharing.max.age	Bilangan bulat	Baca/Tulis	Nilai dari <MaxAge>	Permintaan proxy
cross_origin_resource_sharing.preflight.accepted	Boolean	Baca/Tulis	Menunjukkan apakah permintaan preflight diterima	Permintaan proxy
cross_origin_resource_sharing.request.headers	String	Baca/Tulis	Nilai header permintaan Access-Control-Request-Headers	Permintaan proxy
cross_origin_resource_sharing.request.method	String	Baca/Tulis	Nilai header permintaan Access-Control-Request-Method	Permintaan proxy
cross_origin_resource_sharing.request.origin	String	Baca/Tulis	Sama dengan request.header.origin	Permintaan proxy
cross_origin_resource_sharing.request.type	String	Baca/Tulis	Jenis permintaan CORS. Nilai yang memungkinkan: AKTUAL: Permintaan yang bukan permintaan preflight PRE_FLIGHT: Permintaan preflight	Permintaan proxy