Cross-origin resource sharing (CORS) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. With CORS support in Amazon S3, you can build rich client-side web applications with Amazon S3 and selectively allow cross-origin access to your Amazon S3 resources.
This section provides an overview of CORS. The subtopics describe how you can enable CORS using the Amazon S3 console, or programmatically using the Amazon S3 REST API and the AWS SDKs.
The following are example scenarios for using CORS:
Example 1: Suppose you are hosting a website in an Amazon S3 bucket named
described in Hosting a Static Website on Amazon S3. Your users
load the website endpoint
http://website.s3-website-us-east-1.amazonaws.com. Now you want to use
authenticated GET and PUT requests against the same bucket by using the Amazon S3's API
endpoint for the bucket,
website.s3.amazonaws.com. A browser would normally
bucket to explicitly enable cross-origin requests from
Example 2: Suppose you want to host a web font from your S3 bucket. Again, browsers require a CORS check (also referred as a preflight check) for loading web fonts, so you would configure the bucket that is hosting the web font to allow any origin to make these requests.
To configure your bucket to allow cross-origin requests, you create a CORS configuration,
an XML document with rules that identify the origins that you will allow to access your
bucket, the operations (HTTP methods) will support for each origin, and other
operation-specific information. You can add up to 100 rules to the configuration. You add the
XML document as the
cors subresource to the bucket.
For example, the following
cors configuration on a bucket has three rules,
which are specified as
The first rule allows cross-origin PUT, POST, and DELETE requests from the
https://www.example1.com origin. The rule also allows all headers in a
preflight OPTIONS request through the
In response to any preflight OPTIONS request, Amazon S3 will return any requested
The second rule allows same cross-origin requests as the first rule but the rule
applies to another origin,
The third rule allows cross-origin GET requests from all origins. The '*' wildcard character refers to all origins.
<CORSConfiguration> <CORSRule> <AllowedOrigin>http://www.example1.com</AllowedOrigin> <AllowedMethod>PUT</AllowedMethod> <AllowedMethod>POST</AllowedMethod> <AllowedMethod>DELETE</AllowedMethod> <AllowedHeader>*</AllowedHeader> </CORSRule> <CORSRule> <AllowedOrigin>http://www.example2.com</AllowedOrigin> <AllowedMethod>PUT</AllowedMethod> <AllowedMethod>POST</AllowedMethod> <AllowedMethod>DELETE</AllowedMethod> <AllowedHeader>*</AllowedHeader> </CORSRule> <CORSRule> <AllowedOrigin>*</AllowedOrigin> <AllowedMethod>GET</AllowedMethod> </CORSRule> </CORSConfiguration>
The CORS configuration also allows optional configuration parameters, as shown in the
following CORS configuration. In this example, the following CORS configuration allows
cross-origin PUT and POST requests from the
<CORSConfiguration> <CORSRule> <AllowedOrigin>http://www.example.com</AllowedOrigin> <AllowedMethod>PUT</AllowedMethod> <AllowedMethod>POST</AllowedMethod> <AllowedMethod>DELETE</AllowedMethod> <AllowedHeader>*</AllowedHeader> <MaxAgeSeconds>3000</MaxAgeSeconds> <ExposeHeader>x-amz-server-side-encryption</ExposeHeader> <ExposeHeader>x-amz-request-id</ExposeHeader> <ExposeHeader>x-amz-id-2</ExposeHeader> </CORSRule> </CORSConfiguration>
CORSRule element in the preceding configuration includes the following
MaxAgeSeconds—Specifies the amount of time in seconds (in this
example, 3000) that the browser will cache an Amazon S3 response to a preflight OPTIONS request
for the specified resource. By caching the response, the browser does not have to send
preflight requests to Amazon S3 if the original request is to be repeated.
ExposeHeader—Identifies the response headers (in this example,
x-amz-id-2) that customers will be able to access from their applications
In the CORS configuration, you can specify the following values for the
AllowedOrigin element you specify the origins that you want to allow
cross-domain requests from, for example,
http://www.example.com. The origin
string can contain at most one
* wildcard character, such as
http://*.example.com. You can optionally specify
* as the origin
to enable all the origins to send cross-origin requests. You can also specify
https to enable only secure origins.
AllowedHeader element specifies which headers are allowed in a
preflight request through the
Access-Control-Request-Headers header. Each
header name in the
Access-Control-Request-Headers header must match a
corresponding entry in the rule. Amazon S3 will send only the allowed headers in a response that
were requested. For a sample list of headers that can be used in requests to Amazon S3, go to
Common Request Headers in
the Amazon Simple Storage Service API Reference guide.
Each AllowedHeader string in the rule can contain at most one * wildcard character. For
<AllowedHeader>x-amz-*</AllowedHeader> will enable all
ExposeHeader element identifies a header in the response that you want
customers to be able to access from their applications (for example, from a JavaSript
XMLHttpRequest object). For a list of common Amazon S3 response headers, go to
Common Response Headers in
the Amazon Simple Storage Service API Reference guide.
MaxAgeSeconds element specifies the time in seconds that your browser
can cache the response for a preflight request as identified by the resource, the HTTP
method, and the origin.
When Amazon S3 receives a preflight request from a browser, it evaluates the CORS configuration
for the bucket and uses the first
CORSRule rule that matches the incoming browser
request to enable a cross-origin request. For a rule to match, the following conditions must
Origin header must match an
The request method (for example, GET or PUT) or the
Access-Control-Request-Method header in case of a preflight
OPTIONS request must be one of the
Every header listed in the request's
header on the preflight request must match an
The ACLs and policies continue to apply when you enable CORS on the bucket.