The same-origin policy is a security policy enforced on
client-side web applications (like web browsers) to prevent interactions between
resources from different origins. While useful for preventing malicious behavior,
this security measure also prevents legitimate interactions between known
origins. For example, a script on a page hosted on App Engine at
example.appspot.com
might need to use resources stored in a Cloud Storage
bucket at example.storage.googleapis.com
. However, because these are two
different origins from the perspective of the browser, the browser won't allow a
script from example.appspot.com
to fetch resources from
example.storage.googleapis.com
.
The Cross Origin Resource Sharing (CORS) spec was developed by
the World Wide Web Consortium (W3C) to get around this limitation.
Cloud Storage supports this specification by allowing you to configure
your buckets to support CORS. Continuing the above example, you can configure
the example.storage.googleapis.com
bucket so that a browser can share its
resources with scripts from example.appspot.com
.
For more information about CORS configuration elements, see Set Bucket CORS.
How CORS works
There are two types of CORS requests: simple and preflighted. A simple request can be initiated directly. A preflighted request must send a preliminary, "preflight" request to the server to get permission before the primary request can proceed. A request is preflighted if any of the following circumstances are true:
- It uses methods other than
GET
,HEAD
orPOST
. - It uses the
POST
method with aContent-Type
other thantext/plain
,application/x-www-form-urlencoded
, ormultipart/form-data
. - It sets custom headers. For example,
X-PINGOTHER
.
The following process occurs when a browser makes a simple request to Cloud Storage:
The browser adds the
Origin
header to the request. TheOrigin
header contains the origin of the resource seeking to share the Cloud Storage bucket's resources, for example,Origin:https://www.example.appspot.com
.Cloud Storage compares the HTTP method of the request and the value of the
Origin
header to the Methods and Origins information in the target bucket's CORS configuration to see if there are matches. If there are, Cloud Storage includes theAccess-Control-Allow-Origin
header in its response. TheAccess-Control-Allow-Origin
header contains the value of theOrigin
header from the initial request.The browser receives the response and checks to see if the
Access-Control-Allow-Origin
value matches the domain specified in the original request. If they do match, the request succeeds. If they don't match, or if theAccess-Control-Allow-Origin
header is not present in the response, the request fails.
A preflighted request performs the following steps first. If it is successful, it then follows the same process as a simple request:
The browser sends an
OPTIONS
request containing theRequested Method
andRequested Headers
of the primary request.Cloud Storage responds back with the values of the HTTP methods and headers allowed by the targeted resource. If any of the method or header values in the preflight request aren't in the set of methods and headers allowed by the targeted resource, the request fails, and the primary request isn't sent.
This is a simplified description of CORS. For a more complete description, read the Fetch spec.
Cloud Storage CORS support
Cloud Storage allows you to set a CORS configuration at the bucket level only. You can set the CORS configuration for a bucket using the gsutil command-line tool, the XML API, or the JSON API. However, the CORS configuration applies only to XML API requests.
Different Cloud Storage endpoints deal with CORS requests in the following ways:
- JSON API endpoints allow CORS requests, regardless of CORS configuration on the target bucket.
- XML API endpoints accept CORS requests based on the CORS configuration on the target bucket.
- The authenticated browser download endpoint
storage.cloud.google.com
does not allow CORS requests. Note that the Cloud Console provides this endpoint for each object's public URL link.
You can use either of the following XML API request URLs to obtain a response from Cloud Storage that contains the CORS headers:
storage.googleapis.com/BUCKET_NAME
BUCKET_NAME.storage.googleapis.com
For information about XML API request URLs, see Request Endpoints.
Elements of a CORS configuration
The values you set on your bucket's CORS configuration determine the CORS headers Cloud Storage returns in an HTTP response:
Field | Description | XML API response behavior | JSON API response behavior |
---|---|---|---|
Origin | Specify Origins that you want to allow for cross origin resource sharing
with this Cloud Storage bucket.
For example, https://origin1.example.com . |
If the origin in a browser's request matches an origin in your CORS
configuration,
Cloud Storage returns Access-Control-Allow-Origin to the
browser. If there is no match, Cloud Storage does not include
Access-Control-Allow-Origin in the response. You can supply a
wildcard value that grants access to all origins:
<Origin>*</Origin> . |
Cloud Storage returns the Access-Control-Allow-Origin
header set to the origin of the request. |
Methods | Specify HTTP methods that you want to allow for cross origin resource
sharing
with this Cloud Storage bucket. The value is returned in the
Since |
Cloud Storage supports the following methods: Cloud Storage checks the methods
sent from the browser in the |
Cloud Storage returns the Access-Control-Allow-Methods
header set to the following methods: DELETE ,
GET , HEAD , PATCH , POST ,
PUT .
|
Response headers | The response header field specifies which headers you want to allow for
cross origin resource sharing with this Cloud Storage bucket. The value is
returned in the Access-Control-Allow-Headers header in response to successful preflight
requests. |
For pre-flight requests, Cloud Storage checks the headers
sent from the browser in the Access-Control-Request-Headers header
against the
bucket's CORS configuration. If there is no match, Cloud Storage doesn't
return CORS response headers. |
Cloud Storage returns the Access-Control-Allow-Headers header
set equal to the values specified by the Access-Control-Request-Headers header. |
Max Age in Seconds (optional) | The MaxAgeSec field specifies the number of seconds the browser
is allowed to
make requests before it must repeat the preflight request. This is also
known as the cache expiry time. This value is returned in the Access-Control-Max-Age
header in responses to preflight requests. For example,
3600 sets the cache expiry time to 1 hour. |
Cloud Storage returns the Access-Control-Max-Age
header with the specified cache expiry time. If you omit this field,
Cloud Storage returns the default value of 3600 . |
Cloud Storage returns the Access-Control-Max-Age
header with the default value of 3600 . |
Additional considerations | |||
Credentials | Cloud Storage currently does not support credentials for CORS. | Cloud Storage never returns the Access-Control-Allow-Credentials
header. |
For simple requests, if the CORS request is approved and
valid, the For preflight requests, if |
Exposed headers | The Access-Control-Expose-Headers response header lists header
names that are exposed as part of the response. |
For simple requests, Access-Control-Expose-Headers lists
the values of the response headers in your CORS configuration. |
For simple requests, Access-Control-Expose-Headers returns the values
specified in Access-Control-Request-Headers if they are part of
a list of common HTTP headers. |
Client-side CORS support
Most browsers use the XMLHttpRequest
object to make a cross-domain request.
XMLHttpRequest
takes care of all the work of inserting the right headers and
handling the CORS interaction with the server. You don't have to add any new
code to take advantage of CORS support on Cloud Storage buckets.
What's next
- Learn how to enable CORS for your bucket.
- See the XML reference page for a CORS configuration.