Cross-origin resource sharing (CORS)

Go to examples

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 or POST.
  • It uses the POST method with a Content-Type other than text/plain, application/x-www-form-urlencoded, or multipart/form-data.
  • It sets custom headers. For example, X-PINGOTHER.

The following process occurs when a browser makes a simple request to Cloud Storage:

  1. The browser adds the Origin header to the request. The Origin header contains the origin of the resource seeking to share the Cloud Storage bucket's resources, for example, Origin:https://www.example.appspot.com.

  2. 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 the Access-Control-Allow-Origin header in its response. The Access-Control-Allow-Origin header contains the value of the Origin header from the initial request.

  3. 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 the Access-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:

  1. The browser sends an OPTIONS request containing the Requested Method and Requested Headers of the primary request.

  2. 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 Access-Control-Allow-Methods header in response to successful pre-flight requests.

Since OPTIONS is a standard method that browsers use to initiate preflight requests, you shouldn't specify OPTIONS in your CORS configuration.

Cloud Storage supports the following methods: DELETE, GET, HEAD, POST, PUT.

Cloud Storage checks the methods sent from the browser in the Access-Control-Request-Methods header against the bucket's CORS configuration. If there is no match, Cloud Storage Cloud Storage returns a 200 response code without CORS response headers.

 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 Access-Control-Allow-Credentials header is set to true.

For preflight requests, if Access-Control-Request-Method is empty, Cloud Storage sets Access-Control-Allow-Credentials to true and rejects the request with 404 - Not Found.
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