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
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
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
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
- It uses the
POSTmethod with a
- It sets custom headers.
The following process occurs when a browser makes a simple request to Cloud Storage:
- The browser adds the
Originheader to the request. The
Originheader contains the origin of the resource seeking to share the other domain's resources, for example,
- Cloud Storage compares the HTTP method of the request and the value of the
Originheader 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 the
Access-Control-Allow-Originheader in its response. The
Access-Control-Allow-Originheader contains the value of the
Originheader from the initial request.
- The browser receives the response and checks to see if the
Access-Control-Allow-Originvalue matches the domain specified in the original request. If they do match, the request succeeds. If they don't match, or if the
Access-Control-Allow-Originheader 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
OPTIONSrequest containing the
Requested Headersof the primary request.
- The server 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 very simplified description of CORS. For a more complete description, read the Cross Origin Resource Sharing spec.
Cloud Storage CORS support
Cloud Storage allows you to set 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. For more information about setting CORS
configuration on a bucket, see
Configuring Cross-Origin Resource Sharing (CORS).
For more information about CORS configuration elements, see
Set Bucket CORS.
CORS configuration only affects XML API requests. The JSON API allows CORS requests, regardless of CORS settings on the target bucket.
You can use either of the following XML API request URLs to obtain a response from Cloud Storage that contains the CORS headers:
For information about XML API request URLs, see Request Endpoints.
Client-side CORS support
Most browsers use the
XMLHttpRequest object to make a cross-domain
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.