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.
Configuring 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 it will accept. You can use the gsutil command-line tool, the XML API, the JSON API, or the client libraries for Cloud Storage to set CORS configuration on a bucket.
The following example shows how to configure CORS on your bucket:
gsutil
Create a JSON file that contains the following:
[ { "origin": ["ORIGIN"], "method": ["METHOD"], "responseHeader": ["HEADER"], "maxAgeSeconds": MAX-AGE } ]
Where:
ORIGIN
is an origin allowed for cross origin resource sharing with this bucket. For example,https://example.appspot.com
.METHOD
is an HTTP method allowed for cross origin resource sharing with this bucket. For example,GET
orPUT
.HEADER
is a header allowed for cross origin resource sharing with this bucket. For example,Content-Type
.MAX-AGE
is the number of seconds the browser is allowed to make requests before it must repeat the preflight request. For example,3600
.
For more information, see Elements of a CORS configuration.
Use the
gsutil cors
command to configure CORS on a bucket:gsutil cors set JSON_FILE_NAME.json gs://BUCKET_NAME
Where
JSON_FILE_NAME
is the path to the JSON file you created in Step 1.BUCKET_NAME
is the name of the bucket. For example,my-bucket
.
Code samples
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 Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
You cannot currently configure CORS with the C# client library.
For more information, see the
Cloud Storage PHP API reference documentation.
To set a CORS configuration for a bucket using PHP,
see the Google\Cloud\Storage\Bucket reference documentation.C++
Go
Java
Node.js
Python
Ruby
C#
PHP
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a JSON file that contains the following:
{ "cors": [ { "origin": [ "ORIGIN" ], "method": [ "METHOD" ], "responseHeader": [ "HEADER" ], "maxAgeSeconds": MAX-AGE } ] }
Where:
ORIGIN
is an origin allowed for cross origin resource sharing with this bucket. For example,https://example.appspot.com
.METHOD
is an HTTP method allowed for cross origin resource sharing with this bucket. For example,GET
orPUT
.HEADER
is a header allowed for cross origin resource sharing with this bucket. For example,Content-Type
.MAX-AGE
is the number of seconds the browser is allowed to make requests before it must repeat the preflight request. For example,3600
.
For more information, see Elements of a CORS configuration.
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl --request PATCH \ 'https://storage.googleapis.com/storage/v1/b/BUCKET_NAME' \ --header 'Authorization: Bearer OAUTH2_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary @JSON_FILE_NAME.json
Where:
BUCKET_NAME
is the name of the bucket. For example,my-bucket
.OAUTH2_TOKEN
is the access token you generated in Step 1.JSON_FILE_NAME
is the path to the 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.
Create an XML file that contains the following:
<?xml version="1.0" encoding="UTF-8"?> <CorsConfig> <Cors> <Origins> <Origin>ORIGIN</Origin> </Origins> <Methods> <Method>METHOD</Method> </Methods> <ResponseHeaders> <ResponseHeader>HEADER</ResponseHeader> </ResponseHeaders> <MaxAgeSec>MAX-AGE</MaxAgeSec> </Cors> </CorsConfig>
Where:
ORIGIN
is an origin allowed for cross origin resource sharing with this bucket. For example,https://example.appspot.com
.METHOD
is an HTTP method allowed for cross origin resource sharing with this bucket. For example,GET
orPUT
.HEADER
is a header allowed for cross origin resource sharing with this bucket. For example,Content-Type
.MAX-AGE
is the number of seconds the browser is allowed to make requests before it must repeat the preflight request. For example,3600
.
For more information, see Elements of a CORS configuration.
Use
cURL
to call the XML API with aSet Bucket CORS
request:curl -X PUT --data-binary @XML_FILE_NAME.xml \ -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
.XML_FILE_NAME
is the path to the file you created in Step 2.
Viewing the CORS configuration for a bucket
To view the CORS configuration for a bucket:
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.
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.
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
.
Removing CORS from a bucket
To remove the CORS configuration from a bucket:
gsutil
Create a JSON file that contains the following:
[]
Use the
gsutil cors
command to configure CORS on a bucket:gsutil cors set JSON_FILE_NAME.json gs://BUCKET_NAME
Where
JSON_FILE_NAME
is the path to the JSON file you created in Step 1.BUCKET_NAME
is the name of the bucket. For example,my-bucket
.
Code samples
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 Python API reference documentation.
For more information, see the
Cloud Storage Ruby API reference documentation.
For more information, see the
Cloud Storage C# API reference documentation.
You cannot currently work with CORS using the C# client library.
For more information, see the
Cloud Storage PHP API reference documentation.
To work with CORS configurations for a bucket using PHP,
see the Google\Cloud\Storage\Bucket reference documentation.C++
Go
Java
Node.js
Python
Ruby
C#
PHP
REST APIs
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
Create a JSON file that contains the following:
{ "cors": [] }
Use
cURL
to call the JSON API with aPATCH
Bucket request:curl --request PATCH \ 'https://storage.googleapis.com/storage/v1/b/BUCKET_NAME' \ --header 'Authorization: Bearer OAUTH2_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary @JSON_FILE_NAME.json
Where:
BUCKET_NAME
is the name of the bucket. For example,my-bucket
.OAUTH2_TOKEN
is the access token you generated in Step 1.JSON_FILE_NAME
is the path to the 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.
Create an XML file that contains the following:
<CorsConfig></CorsConfig>
Use
cURL
to call the XML API with aSet Bucket CORS
request:curl -X PUT --data-binary @XML_FILE_NAME.xml \ -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
.XML_FILE_NAME
is the path to the file you created in Step 2.
Troubleshooting CORS requests
If you run into unexpected behavior when accessing Cloud Storage buckets from a different origin, try the following steps:
Use
gsutil cors get
on the target bucket to get its CORS configuration. If you have multiple CORS configuration entries, make sure that as you go through the following steps that the request values map to values in the same 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.
What's next
- Learn more about Cross Origin Resource Sharing (CORS).