SetupConfiguration samples

Cross-Origin Resource Sharing (CORS) enables client-side web applicationsto access resources from different origins. Cloud Storage supports theCORS specification, letting you configure your buckets to share resourcessecurely with scripts from other origins. For example, you can use CORS toenable your web applicationhttps://example-app.appspot.com to access aresource at the originhttps://example-data.storage.googleapis.com.

For more information about CORS configuration components, seeSet Bucket CORS.

How CORS works

Use CORS when you want your website to fetch files, images, or scripts directlyfrom a Cloud Storage bucket using a browser-based request.

Allowing access across domains

By default, web browsers enforce a security measure calledsame-origin policy. Same-origin policy prevents a script on one websitefrom interacting with resources on a different domain. Although this protectsusers from malicious sites, it also blocks legitimate requests. For example, ifyour web applicationhttps://example-app.appspot.com attempts to access aresource at the originhttps://example-data.storage.googleapis.com, the browser willblock the request by default because the domains don't match.

TheCORS specification provides a way for servers to tell the browser,"I trust this specific domain, so go ahead and allow the request."

Cloud Storage lets you set a CORS configuration on your bucket. Whenconfigured, Cloud Storage sends specific HTTP headers back to thebrowser (such asAccess-Control-Allow-Origin) that authorize the browser toshare the bucket's resources with your web application.

Request types

CORS requests operate in two ways: simple and preflighted. Asimple request proceeds directly, while apreflighted request firstsends a preliminary request to obtain permission.

Simple requests

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

1. The browser adds theOrigin header to the request. TheOrigin headercontains the origin of the resource seeking to share theCloud Storage bucket's resources, for example,Origin:https://www.example-app.appspot.com.

2. Cloud Storage compares the HTTP method of the request and the valueof theOrigin header to theMethods andOrigins information in thetarget bucket's CORS configuration to see if there are matches. If there are,Cloud Storage includes theAccess-Control-Allow-Origin header inits response. TheAccess-Control-Allow-Origin header contains the value oftheOrigin header from the initial request.

3. The browser receives the response and checks to see if theAccess-Control-Allow-Origin value matches the domain specified in theoriginal request. If they do match, the request succeeds. If they don'tmatch, or if theAccess-Control-Allow-Origin header isnot present in the response, the request fails.

Preflighted requests

A request is preflighted if any of the following circumstances are true:

• It uses methods other thanGET,HEAD orPOST.
• It uses thePOST method with aContent-Type other thantext/plain,application/x-www-form-urlencoded, ormultipart/form-data.
• It sets custom headers. For example,X-PINGOTHER.

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 anOPTIONS request containing theRequested Method andRequested Headers of the primary request.

2. Cloud Storage responds back with the values of the HTTP methods andheaders allowed by the targeted resource. If any of the method or headervalues in the preflight request aren't in the set of methods and headersallowed by the targeted resource, the request fails, and the primary requestisn't sent.

For a more complete description of CORS requests, read theFetch spec.

Cloud Storage CORS support

Cloud Storage lets you set CORS configurations at the bucket level. TheJSON API and XML API endpoints handle CORS requests and return response headersdifferently. Understand these behaviors to configure your buckets effectively:

• JSON API endpoints always allow CORS requests and return default values in theCORS response headers, regardless of the configuration set on the bucket.

• XML API endpoints only allow CORS requests based on the configuration on thebucket and return specific CORS header values in response to thatconfiguration.

• The authenticated browser download endpointstorage.cloud.google.com doesnot allow CORS requests. Note that the Google Cloud console provides thisendpoint for each object's public URL link.

You can use either of the following XML API request URLs to obtain a responsefrom Cloud Storage that contains the CORS headers:

storage.googleapis.com/BUCKET_NAME

BUCKET_NAME.storage.googleapis.com

For information about XML API request URLs, seeRequest Endpoints.

Components of a CORS configuration

When using the XML API, the values you set on your bucket's CORS configurationdetermine the CORS headers Cloud Storage returns in an HTTP response.When using the JSON API, Cloud Storage does not evaluate your bucket'sconfiguration and instead returns default header values.

The following table describes the fields in a CORS configuration and theresponse behavior of the XML and JSON APIs. To learn how these fields are used,seeCORS configuration examples.

¹ Names documented in the Field column are specific to the JSON API.When using the XML API to set a CORS configuration, use theXML-specific format.

Specifying multiple origins, methods, or headers

To learn how to set multiple origins, methods, or headers in a CORSconfiguration, see the following list:

• When using the JSON API, you can specify multiple origins, methods, or headersby using a comma-separated array. For example,"method": ["GET", "PUT"].

  Caution: When you set a CORS configuration using the JSON API, requests fromall origins are accepted regardless of theorigin field value in the CORSconfiguration.

• When using the XML API, you can specify multiple origins, methods, or headersby using separate elements. For example:

  <Methods><Method>PUT</Method><Method>GET</Method></Methods>

• To allow requests to be made from any origin, set the origin to the wildcard*. For example,"origin": ["*"] in the JSON API or<Origin>*</Origin> inthe XML API. While this origin is helpful for testing configurations, in mostcases, you'll want to restrict request origins to prevent unwanted usage ofyour resources.

Additional considerations

The following table describes considerations when making requests usingcredentials or access control headers:

Allowing buckets to access external resources

Sometimes, you might want to allow scripts hosted in Cloud Storage toaccess static resources that are hosted on a website external toCloud Storage. In this scenario, the website serves CORS headers sothat content onstorage.googleapis.com is allowed access.

As a best practice, you should dedicate a specific bucket for this data access.This approach prevents your site from inadvertently over-exposing staticresources to all ofstorage.googleapis.com. For example, if you want todedicate a bucket namedmybucket for data access, you should have the websiteserve the CORS headerAccess-Control-Allow-Origin: https://mybucket.storage.googleapis.com insteadofAccess-Control-Allow-Origin: https://storage.googleapis.com.

Client-side CORS support

Most browsers use theXMLHttpRequest object to make a cross-domain request.XMLHttpRequest takes care of all the work of inserting the right headers andhandling the CORS interaction with the server. You don't have to add any newcode to take advantage of CORS support on Cloud Storage buckets.

What's next

• Learn how toenable CORS for your bucket.
• ExploreCORS configuration examples, including an example that removesthe CORS configuration on a bucket.
• Learn how totroubleshoot CORS requests.