Enabling CORS for a REST API resource
Cross-origin resource
sharing (CORS)
Determining whether to enable CORS support
A cross-origin HTTP request is one that is made to:
-
A different domain (for example, from
example.com
toamazondomains.com
) -
A different subdomain (for example, from
example.com
topetstore.example.com
) -
A different port (for example, from
example.com
toexample.com:10777
) -
A different protocol (for example, from
https://example.com
tohttp://example.com
)
Cross-origin HTTP requests can be divided into two types: simple requests and non-simple requests.
An HTTP request is simple if all of the following conditions are true:
-
It is issued against an API resource that allows only
GET
,HEAD
, andPOST
requests. -
If it is a
POST
method request, it must include anOrigin
header. -
The request payload content type is
text/plain
,multipart/form-data
, orapplication/x-www-form-urlencoded
. -
The request does not contain custom headers.
-
Any additional requirements that are listed in the Mozilla CORS documentation for simple requests
.
For simple cross-origin POST
method requests, the response from your
resource needs to include the header Access-Control-Allow-Origin
, where the
value of the header key is set to '*'
(any origin) or is set to the origins
allowed to access that resource.
All other cross-origin HTTP requests are non-simple requests. If your API's resources receive non-simple requests, you need to enable CORS support.
What it means to enable CORS support
When a browser receives a non-simple HTTP request, the CORS protocol
-
Includes an
Origin
header. -
Uses the
OPTIONS
method. -
Includes the following headers:
-
Access-Control-Request-Method
-
Access-Control-Request-Headers
-
To support CORS, therefore, a REST API resource needs to implement an
OPTIONS
method that can respond to the OPTIONS
preflight
request with at least the following response headers mandated by the Fetch
standard:
-
Access-Control-Allow-Methods
-
Access-Control-Allow-Headers
-
Access-Control-Allow-Origin
How you enable CORS support depends on your API's integration type.
Enabling CORS support for mock integrations
For a mock integration, you enable CORS by creating an OPTIONS
method
to return the required response headers (with appropriate static values) as the
method response headers. In addition, each of the actual CORS-enabled methods must
also return the Access-Control-Allow-Origin:'
header in at least its 200 response,
where the value of the header key is set to request-originating
server addresses
''*'
(any origin) or is set
to the origins allowed to access the resource.
Enabling CORS support for Lambda or HTTP non-proxy integrations and AWS service integrations
For a Lambda custom (non-proxy) integration, HTTP custom (non-proxy) integration,
or AWS service integration, you can set up the required headers by using API Gateway
method response and integration response settings. When you enable CORS by using the
AWS Management Console, API Gateway creates an OPTIONS
method and attempts to add the
Access-Control-Allow-Origin
header to your existing method
integration responses. This doesn’t always work, and sometimes you need to manually
modify the integration response to properly enable CORS. Usually this just means
manually modifying the integration response to return the
Access-Control-Allow-Origin
header.
Enabling CORS support for Lambda or HTTP proxy integrations
For a Lambda proxy integration or HTTP proxy integration, you can still set up the
required OPTIONS
response headers in API Gateway. However, your backend is
responsible for returning the Access-Control-Allow-Origin
and
Access-Control-Allow-Headers
headers, because a proxy integration
doesn't return an integration response.
The following example Lambda functions return the required CORS headers: