Cross Origin Resource Sharing (CORS) allows interactions between resources from different origins, something that is normally prohibited in order to prevent malicious behavior. Use this topic to learn how to configure CORS on a Cloud Storage bucket.
Configure CORS on a bucket
You set a CORS configuration on a bucket by specifying information, such as HTTP methods and originating domains, that identify the types of requests the bucket can accept.
Use the following steps to set a CORS configuration on your bucket:
Console
You cannot manage CORS using the Cloud console. Use gsutil instead.
gsutil
Create a JSON file with the CORS configuration you would like to apply. See configuration examples for sample JSON files.
Use the
gsutil cors
command to apply the configuration to a bucket:gsutil cors set CORS_CONFIG_FILE gs://BUCKET_NAME
Where:
CORS_CONFIG_FILE
is the path to the JSON file you created in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Code samples
For more information, see the
Cloud Storage C++ API reference documentation.
The following sample sets a CORS configuration on a bucket: The following sample removes any existing CORS configuration from on a bucket:
For more information, see the
Cloud Storage C# API reference documentation.
The following sample sets a CORS configuration on a bucket: The following sample removes any existing CORS configuration from on a bucket:
For more information, see the
Cloud Storage Go API reference documentation.
The following sample sets a CORS configuration on a bucket: The following sample removes any existing CORS configuration from on a bucket:
For more information, see the
Cloud Storage Java API reference documentation.
The following sample sets a CORS configuration on a bucket: The following sample removes any existing CORS configuration from on a bucket:
For more information, see the
Cloud Storage Node.js API reference documentation.
The following sample sets a CORS configuration on a bucket: The following sample removes any existing CORS configuration from on a bucket:
For more information, see the
Cloud Storage PHP API reference documentation.
The following sample sets a CORS configuration on a bucket: The following sample removes any existing CORS configuration from on a bucket:
For more information, see the
Cloud Storage Python API reference documentation.
The following sample sets a CORS configuration on a bucket: The following sample removes any existing CORS configuration from on a bucket:
For more information, see the
Cloud Storage Ruby API reference documentation.
The following sample sets a CORS configuration on a bucket: The following sample removes any existing CORS configuration from on a bucket:C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Create a JSON file with the CORS configuration you would like to apply. See configuration examples for sample JSON files.
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl --request PATCH \ 'https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=cors' \ --header 'Authorization: Bearer OAUTH2_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary @CORS_CONFIG_FILE
Where:
BUCKET_NAME
is the name of the bucket. For example,my-bucket
.OAUTH2_TOKEN
is the access token you generated in Step 1.CORS_CONFIG_FILE
is the path to the JSON file you created in Step 2.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Create a XML file with the CORS configuration you would like to apply. See configuration examples for sample XML files.
Use
cURL
to call the XML API with aSet Bucket CORS
request:curl -X PUT --data-binary @CORS_CONFIG_FILE \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "x-goog-project-id: PROJECT_ID" \ "https://storage.googleapis.com/BUCKET_NAME?cors"
Where:
BUCKET_NAME
is the name of the bucket. For example,my-bucket
.OAUTH2_TOKEN
is the access token you generated in Step 1.PROJECT_ID
is the ID of the project associated with the bucket. For example,my-project
.CORS_CONFIG_FILE
is the path to the XML file you created in Step 2.
View the CORS configuration for a bucket
To view the CORS configuration for a bucket:
Console
You cannot manage CORS using the Cloud console. Use gsutil instead.
gsutil
Use the gsutil cors
command to get the CORS configuration
of a bucket:
gsutil cors get gs://BUCKET_NAME
Where BUCKET_NAME
is the name of the bucket. For
example, my-bucket
.
Code samples
To view the CORS configuration for a bucket using the client libraries, follow the instructions for displaying a bucket's metadata and look for the CORS field in the response:
For more information, see the
Cloud Storage C++ API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
For more information, see the
Cloud Storage Go API reference documentation.
For more information, see the
Cloud Storage Java API reference documentation.
For more information, see the
Cloud Storage Node.js API reference documentation.
For more information, see the
Cloud Storage PHP API reference documentation.
For more information, see the
Cloud Storage Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the JSON API with aGET
Bucket request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=cors"
Where:
OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials. For instructions, see API authentication.
Use
cURL
to call the XML API with aGET
Bucket request:curl -X GET \ -H "Authorization: Bearer OAUTH2_TOKEN" \ "https://storage.googleapis.com/BUCKET_NAME?cors"
Where:
OAUTH2_TOKEN
is the name of the access token you generated in Step 1.BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.
Troubleshoot CORS requests
If you run into unexpected behavior when accessing Cloud Storage buckets from a different origin, try the following steps:
Review the CORS configuration on the target bucket. If you have multiple CORS configuration entries, make sure that the request values you use for troubleshooting map to values in a single CORS configuration entry.
Check that you are not making a request to the
storage.cloud.google.com
endpoint, which doesn't allow CORS requests. For more information about supported endpoints for CORS, see Cloud Storage CORS support.Review a request and response using the tool of your choice. In a Chrome browser, you can use the standard developer tools to see this information:
- Click the Chrome menu
on the browser toolbar.
- Select More Tools > Developer Tools.
- Click the Network tab.
- From your application or command line, send the request.
- In the pane displaying the network activity, locate the request.
- In the Name column, click the name corresponding to the request.
- Click the Headers tab to see the response headers, or the Response tab to see the content of the response.
If you're not seeing a request and response, it is possible that your browser has cached an earlier failed preflight request attempt. Clearing your browser's cache should also clear the preflight cache. If it doesn't, set the
MaxAgeSec
value in your CORS configuration to a lower value (the default value is 1800 (30 minutes) if not specified), wait for however long the oldMaxAgeSec
was, then try the request again. This performs a new preflight request, which fetches the new CORS configuration and purges the cache entries. Once you have debugged your problem, raiseMaxAgeSec
back to a higher value, to reduce the preflight traffic to your bucket.- Click the Chrome menu
Ensure that the request has an
Origin
header and that the header value matches at least one of theOrigins
values in the bucket's CORS configuration. Note that the scheme, host, and port of the values must match exactly. Some examples of acceptable matches are as follows:http://origin.example.com
matcheshttp://origin.example.com:80
(because 80 is the default HTTP port), but does not matchhttps://origin.example.com
,http://origin.example.com:8080
,http://origin.example.com:5151
, orhttp://sub.origin.example.com
.https://example.com:443
matcheshttps://example.com
but nothttp://example.com
orhttp://example.com:443
.http://localhost:8080
only matches exactlyhttp://localhost:8080
, nothttp://localhost:5555
orhttp://localhost.example.com:8080
.
Ensure that the HTTP method of the request (if this is a simple request), or the method specified in
Access-Control-Request-Method
(if this a preflight request), matches at least one of theMethods
values in the bucket's CORS configuration.If this is a preflight request, see if it includes one or more
Access-Control-Request-Header
headers. If so, then ensure that eachAccess-Control-Request-Header
value matches aResponseHeader
value in the bucket's CORS configuration. All headers named in theAccess-Control-Request-Header
must be in the CORS configuration for the preflight request to succeed and include CORS headers in the response.
CORS configuration examples
The following examples show specific CORS configurations that you can set on buckets.
Basic CORS configuration
Say you have a dynamic website running on App Engine, which users can
access at your-example-website.appspot.com
. You have a font file hosted in a
Cloud Storage bucket named your-example-bucket
. You'd like to use
the font on your website, so you must apply a CORS configuration on
your-example-bucket
that enables your users' browsers to request resources
from the bucket. Based on the configuration below, preflight requests are valid
for 1 hour, and successful browser requests return the Content-Type
of the
resource in the response.
gsutil
[ { "origin": ["https://your-example-website.appspot.com"], "method": ["GET"], "responseHeader": ["Content-Type"], "maxAgeSeconds": 3600 } ]
Note that you can specify multiple origins, methods, or headers using
a comma-separated list. For example, "method": ["GET", "PUT"]
.
For more information on how to set a CORS configuration, see the
gsutil cors
documentation.
REST APIs
JSON API
{ "cors": [ { "origin": ["https://your-example-website.appspot.com"], "method": ["GET"], "responseHeader": ["Content-Type"], "maxAgeSeconds": 3600 } ] }
Note that you can specify multiple origins, methods, or headers using
a comma-separated list. For example, "method": ["GET", "PUT"]
.
For the generalized format of a CORS configuration file, see the bucket resource representation for JSON.
XML API
<?xml version="1.0" encoding="UTF-8"?> <CorsConfig> <Cors> <Origins> <Origin>https://your-example-website.appspot.com</Origin> </Origins> <Methods> <Method>GET</Method> </Methods> <ResponseHeaders> <ResponseHeader>Content-Type</ResponseHeader> </ResponseHeaders> <MaxAgeSec>3600</MaxAgeSec> </Cors> </CorsConfig>
Note that you can specify multiple origins, methods, or headers using
separate elements for each. For example, having <Method>GET</Method>
and <Method>PUT</Method>
within the <Methods>
element.
For the generalized format of a CORS configuration file, see the CORS configuration format for XML.
Remove the CORS configuration
When set on a bucket, the following configuration removes all current CORS settings for a bucket:
gsutil
[]
For more information on how to set a CORS configuration, see the
gsutil cors
documentation.
REST APIs
JSON API
{ "cors": [] }
For the generalized format of a CORS configuration file, see the bucket resource representation for JSON.
XML API
<CorsConfig></CorsConfig>
For the generalized format of a CORS configuration file, see the CORS configuration format for XML.
What's next
- Learn more about Cross Origin Resource Sharing (CORS).