Help Center/ API Gateway/ User Guide (ME-Abu Dhabi Region)/ API Policies/ CORS
Updated on 2024-10-09 GMT+08:00
View PDF
Share

CORS

For security purposes, the browser restricts cross-domain requests from being initiated from a page script. In this case, the page can access only the resources from the current domain. CORS allows the browser to send XMLHttpRequest to the server in a different domain. For details about CORS, see CORS.

The CORS plug-in provides the capabilities of specifying preflight request headers and response headers and automatically creating preflight request APIs for cross-origin API access.

If your gateway does not support this policy, contact technical support to upgrade the gateway to the latest version.

Usage Guidelines

  • You have understood the Guidelines for Using Plug-ins.
  • APIs with the same request path in an API group can only be bound with the same CORS plug-in policy.
  • If you have enabled CORS for an API and have also bound the CORS plug-in to the API, the CORS plug-in will be used.
  • You cannot bind the CORS plug-in to APIs with the same request path as another API that uses the OPTIONS method.
  • When you bind a plug-in policy to an API (see Binding the Policy to APIs), ensure that the request method of the API is included in allow_methods.

Configuration Parameters

Table 1 Configuration parameters

Parameter

Description

Allowed Origins

Access-Control-Allow-Origin response header, which specifies either a single origin, which tells browsers to allow that origin to access an API; or else — for requests without credentials — the "*" wildcard, to tell browsers to allow any origin to access the API. Separate multiple URIs using commas.

Allowed Methods

Access-Control-Allow-Methods response header, which specifies the HTTP methods allowed when accessing the API. Separate multiple methods using commas.

Allowed Headers

Access-Control-Allow-Headers response header, which specifies request headers that can be used when making an XMLHttpRequest. Separate multiple headers using commas.

By default, simple request headers Accept, Accept-Language, Content-Language, and Content-Type (only if the value is application/x-www-form-urlencoded, multipart/form-data, or text/plain) are carried in requests. You do not need to configure these headers in this parameter.

NOTE:
  • When you create a CORS policy, Allowed Headers is blank by default, which means cross-domain requests cannot carry any custom headers.
  • Setting Allowed Headers to an asterisk (*) means cross-domain requests can carry any custom headers.

Exposed Headers

Access-Control-Expose-Headers response header, which specifies which response headers can be contained in the response of XMLHttpRequest. Separate multiple headers using commas.

By default, basic response headers Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, and Pragma can be contained in the response. You do not need to configure these headers in this parameter.

NOTE:
  • When you create a CORS policy, Exposed Headers is blank by default, which means the JavaScript code of a browser cannot parse the headers in a cross-domain access response. However, the following basic response headers obtained using the getResponseHeader() method of the XMLHttpRequest object are excluded: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, and Pragma.
  • Setting Exposed Headers to an asterisk (*) means the JavaScript code of a browser can parse all the headers in a cross-domain access response.

Maximum Age

Access-Control-Max-Age response header, which specifies for how many seconds the results of a preflight request can be cached. No more preflight requests will be sent within the specified period.

Allowed Credentials

Access-Control-Allow-Credentials response header, which specifies whether XMLHttpRequest requests can carry cookies.

Example Script

{
  "allow_origin": "*",
  "allow_methods": "GET,POST,PUT",
  "allow_headers": "Content-Type,Accept,Accept-Ranges,Cache-Control",
  "expose_headers": "X-Request-Id,X-Apig-Latency",
  "max_age": 86400,
  "allow_credentials": true
}
Parent topic: API Policies