Overview Configuration samples
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 set a CORS configuration on a Cloud Storage bucket and how to view the CORS configuration set on a bucket. See Configuration examples for CORS for example CORS configurations, including the configuration that disables any existing configuration on your bucket.
Set the CORS configuration 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 Google Cloud console. Use the gcloud CLI instead.
Command line
gcloud
Create a JSON file with the CORS configuration you would like to apply. See configuration examples for sample JSON files.
Use the
gcloud storage buckets update
command with the--cors-file
flag:gcloud storage buckets update gs://BUCKET_NAME --cors-file=CORS_CONFIG_FILE
Where:
BUCKET_NAME
is the name of the relevant bucket. For example,my-bucket
.CORS_CONFIG_FILE
is the path to the JSON file you created in Step 1.
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
.
Client libraries
For more information, see the
Cloud Storage C++ API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets a CORS configuration on a bucket:
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets a CORS configuration on a bucket:
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets a CORS configuration on a bucket:
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets a CORS configuration on a bucket:
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets a CORS configuration on a bucket:
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets a CORS configuration on a bucket:
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets a CORS configuration on a bucket:
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
The following sample sets a CORS configuration 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 Google Cloud console. Use the gcloud CLI instead.
Command line
gcloud
Use the gcloud storage buckets describe
command with the
--format
flag:
gcloud storage buckets describe gs://BUCKET_NAME --format="default(cors_config)"
Where BUCKET_NAME
is the name of the bucket
whose CORS configuration you want to view. For example, my-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
whose CORS configuration you want to view. For example, my-bucket
.
Client libraries
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.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage C# API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Go API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Java API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Node.js API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage PHP API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Python API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
For more information, see the
Cloud Storage Ruby API
reference documentation.
To authenticate to Cloud Storage, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
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.
What's next
- Explore CORS configuration examples, including an example that removes the CORS configuration on a bucket.
- Learn more about CORS.