Configure CORS on S3

Where the configuration lives

Cross-origin sharing rules apply per bucket. In the AWS Management Console, open the S3 console, choose General purpose buckets, choose the bucket name, select the Permissions tab, scroll down to Cross-origin resource sharing (CORS), and choose Edit. The console editor accepts a JSON document only.

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://app.example.com"],
      "AllowedMethods": ["GET", "PUT"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag"],
      "MaxAgeSeconds": 3000
    },
    {
      "AllowedOrigins": ["*"],
      "AllowedMethods": ["GET"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3000
    }
  ]
}

The document contains a CORSRules array with one or more rule objects. Each rule supports an optional ID string. AllowedOrigins takes exact origins, a wildcard * for all origins, or a subdomain wildcard like http://*.example.com. AllowedMethods accepts GET, PUT, POST, DELETE, and HEAD. AllowedHeaders and ExposeHeaders take explicit header names or *. MaxAgeSeconds sets how long the browser can cache the preflight answer. Choose Save changes to apply the document.

# Write the rules from a local JSON file
aws s3api put-bucket-cors --bucket my-bucket \
  --cors-configuration file://cors.json

# Read them back
aws s3api get-bucket-cors --bucket my-bucket

# Remove the configuration entirely
aws s3api delete-bucket-cors --bucket my-bucket

How S3 evaluates the rules

When S3 receives a preflight request, it evaluates the bucket CORS configuration and applies the first CORSRule that satisfies every matching condition.

• The request Origin header must match an entry in AllowedOrigins.
• The HTTP method named in the Access-Control-Request-Method header must match an entry in AllowedMethods.
• Every header listed in the Access-Control-Request-Headers header must match an entry in AllowedHeaders.

ACLs and bucket policies continue to apply when CORS is active, so a matching rule never makes a private object publicly readable. The MaxAgeSeconds property tells the browser how many seconds to cache the preflight verdict so repeated requests avoid additional round trips.

CloudFront in front of S3

A default CloudFront cache behavior strips the Origin header and disallows OPTIONS requests, which prevents S3 from returning CORS response headers even when the bucket configuration is valid.

• Allow OPTIONS in the cache behavior allowed HTTP methods.
• Forward the Origin header to the bucket, along with Access-Control-Request-Method and Access-Control-Request-Headers when preflight responses should be cached. Header forwarding is configured with a cache policy and an origin request policy.
• The managed origin request policy CORS-S3Origin forwards exactly these headers to S3.
• Alternatively, attach the managed response headers policy SimpleCORS or CORS-With-Preflight to add Access-Control-Allow-Origin directly at the CloudFront edge.

# Cache behavior for a distribution in front of the bucket
Allowed HTTP methods: GET, HEAD, OPTIONS

# Origin request policy: forwards the headers S3 needs to evaluate
# CORS. The managed policy CORS-S3Origin covers exactly this:
#   Origin
#   Access-Control-Request-Method
#   Access-Control-Request-Headers

# Response headers policy (optional, attaches the allow-origin header
# at the edge): managed policy SimpleCORS or CORS-With-Preflight

Verify with curl

A successful actual request returns an access-control-allow-origin header alongside the object payload. A successful preflight probe returns access-control-allow-origin, access-control-allow-methods, and access-control-max-age. S3 omits all CORS headers whenever the request lacks an Origin header, so curl commands must explicitly provide one.

# Actual request: expect access-control-allow-origin on the response
curl -i -H "Origin: https://app.example.com" \
  https://my-bucket.s3.eu-west-1.amazonaws.com/object.json

# Preflight: expect allow-origin, allow-methods and max-age
curl -i -X OPTIONS \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: PUT" \
  https://my-bucket.s3.eu-west-1.amazonaws.com/object.json

An HTTP 403 response on the preflight indicates that no CORSRule matched the incoming origin, method, or request headers. A 200 response that lacks access-control-allow-origin indicates that the origin did not match AllowedOrigins, or that an intermediary such as CloudFront dropped the Origin header before it reached S3. The header checker evaluates pasted headers against the browser rules.

Good questions.