CORS configuration examples

Overview Setup

This page shows example configurations for Cross-origin resource sharing (CORS).

When you set a CORS configuration on a bucket, you allow interactions between resources from different origins, something that is normally prohibited in order to prevent malicious behavior. To learn how to structure a request that sets or edits a CORS configuration on a bucket, see the instructions in Using CORS.

Note the following additional resources:

• For the generalized format of a CORS configuration file, see the bucket resource representation for JSON or the CORS configuration format for XML.

• When sending requests using the Google Cloud CLI, use the correct CORS file configuration structure.

Basic CORS configuration

Say you have a dynamic website which users can access at your-example-website.appspot.com. You have an image file hosted in a Cloud Storage bucket named your-example-bucket. You'd like to use the image 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 following configuration, preflight requests are valid for 1 hour, and successful browser requests return the Content-Type of the resource in the response.

Note: When creating a CORS configuration, you can specify multiple origins, headers, and methods.

JSON API

{
  "cors": [
    {
      "origin": ["https://your-example-website.appspot.com"],
      "method": ["GET"],
      "responseHeader": ["Content-Type"],
      "maxAgeSeconds": 3600
    }
  ]
}

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>

Direct file uploads (for single-page applications)

Use this configuration when your frontend application needs to upload files directly to a bucket, which requires a PUT operation. This is a common need for single-page applications, where the application logic lives in the user's browser instead of in a backend server.

Note that PUT requests always trigger a preflight check.

JSON API

{
 "cors": [
    {
        "origin": ["https://www.example-website.appspot.com"],
        "method": ["PUT", "POST", "OPTIONS"],
        "responseHeader": ["Content-Type", "x-goog-resumable"],
        "maxAgeSeconds": 3600
      }
  ]
}

XML API

<?xml version="1.0" encoding="UTF-8"?>
<CorsConfig>
  <Cors>
    <Origins>
      <Origin>https://your-example-website.appspot.com</Origin>
    </Origins>
    <Methods>
      <Method>PUT</Method>
      <Method>POST</Method>
      <Method>OPTIONS</Method>
    </Methods>
    <ResponseHeaders>
      <ResponseHeader>Content-Type</ResponseHeader>
      <ResponseHeader>x-goog-resumable</ResponseHeader>
    </ResponseHeaders>
    <MaxAgeSec>3600</MaxAgeSec>
  </Cors>
</CorsConfig>

Client-side code sample

JavaScript

// Uploading a file using a Signed URL or direct PUT
await fetch(gcsSignedUrl, {
  method: 'PUT',
  body: fileBlob,
  headers: {
    'Content-Type': 'application/pdf'
  }
});

Authenticated data access

Use this configuration if your application sends a bearer token or a Google Identity header to access protected (non-public) objects.

JSON API

{
 "cors": [
    {
        "origin": ["https://www.example-secure-app.appspot.com"],
        "method": ["GET", "HEAD"],
        "responseHeader": ["Authorization", "Content-Type"],
        "maxAgeSeconds": 3600
      }
  ]
}

XML API

<?xml version="1.0" encoding="UTF-8"?>
<CorsConfig>
  <Cors>
    <Origins>
      <Origin>https://www.example-secure-app.appspot.com</Origin>
    </Origins>
    <Methods>
      <Method>GET</Method>
      <Method>HEAD</Method>
    </Methods>
    <ResponseHeaders>
      <ResponseHeader>Authorization</ResponseHeader>
      <ResponseHeader>Content-Type</ResponseHeader>
    </ResponseHeaders>
    <MaxAgeSec>3600</MaxAgeSec>
  </Cors>
</CorsConfig>

CORS configuration structure for gcloud CLI

The gcloud storage buckets update --cors-file command expects a file containing only the list of CORS rules. When specifying a CORS configuration to be set using the Google Cloud CLI, remove the top level "cors": wrapper from the JSON file.

For example, this gcloud CLI command sets a CORS configuration on a bucket:

gcloud storage buckets update gs://example_bucket --cors-file=example_cors_file.json

This is an example configuration for example_cors_file.json that uses the correct structure for the gcloud storage buckets update --cors-file command.

[
    {
      "origin": ["https://your-example-website.appspot.com"],
      "method": ["GET"],
      "responseHeader": ["Content-Type"],
      "maxAgeSeconds": 3600
    }
]

What's next

• Learn more about Cross Origin Resource Sharing (CORS).
• Set and view the CORS configuration on a bucket.