S3 CORS Configuration for Web Apps

CORS (Cross-Origin Resource Sharing) is a security mechanism implemented by web browsers to control how resources on one origin can be accessed by a web page from a different origin. An "origin" is defined by the scheme (protocol), host (domain), and port. For example, https://www.example.com:443 and http://api.example.com:80 are different origins even though the host is similar. The same-origin policy (SOP) prevents a web page from making requests to a different origin unless explicitly allowed. CORS provides a way for servers to relax SOP by including specific HTTP headers that tell the browser which origins are permitted.

In the context of S3, when a web application hosted on https://myapp.com tries to load a JavaScript file or an image from an S3 bucket https://mybucket.s3.amazonaws.com, the browser checks if the S3 bucket allows https://myapp.com via CORS headers. Without proper CORS configuration, the browser blocks the request and the developer sees a CORS error in the console.

CORS involves two types of requests: simple requests and preflight requests.

Simple Requests – A request is considered simple if it meets all of the following conditions:

For simple requests, the browser sends the actual request directly with an Origin header. The server (S3) responds with an Access-Control-Allow-Origin header if the origin is allowed. If the header matches the requesting origin, the browser allows the response to be shared with the web page. If not, the browser blocks the response.

Preflight Requests – For all other requests (e.g., PUT, DELETE, or requests with custom headers like Authorization or X-Custom-Header), the browser first sends an OPTIONS request to the server with headers: - Origin: the requesting origin. - Access-Control-Request-Method: the HTTP method of the actual request. - Access-Control-Request-Headers: a comma-separated list of custom headers.

The server must respond with appropriate CORS headers: - Access-Control-Allow-Origin: the allowed origin (or * for any). - Access-Control-Allow-Methods: the allowed methods (e.g., GET, PUT, DELETE). - Access-Control-Allow-Headers: the allowed custom headers. - Optionally Access-Control-Max-Age: how long the preflight response can be cached (in seconds).

If the preflight response is valid, the browser proceeds with the actual request. Otherwise, the actual request is never sent.

S3 CORS Configuration – In S3, CORS is configured at the bucket level using a JSON document called a CORS rule. Each rule can contain: - AllowedOrigins: up to one * wildcard or specific origins like https://www.example.com. You can specify multiple origins. - AllowedMethods: one or more of GET, PUT, POST, DELETE, HEAD. - AllowedHeaders: specific headers or * to allow all. - ExposeHeaders: headers that the browser can expose to the client (e.g., ETag, x-amz-request-id). By default, only simple response headers are exposed. - MaxAgeSeconds: time in seconds that the browser caches the preflight response. Default is 0 (no caching). Maximum is 86400 (24 hours).

Default Values – If no CORS rule exists, S3 will not include any CORS headers in responses, causing the browser to block cross-origin requests. There is no default CORS rule; you must explicitly configure it.

Timers – Preflight caching: the MaxAgeSeconds value controls how long the browser can skip the preflight for subsequent requests. A typical value is 3600 (1 hour).

Using AWS Management Console – Navigate to the S3 bucket → Permissions → Cross-origin resource sharing (CORS). Edit the CORS configuration JSON.

Using AWS CLI – Use put-bucket-cors:

aws s3api put-bucket-cors --bucket my-bucket --cors-configuration file://cors.json

Example cors.json:

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://www.example.com"],
      "AllowedMethods": ["GET", "PUT", "POST"],
      "AllowedHeaders": ["*"],
      "ExposeHeaders": ["ETag", "x-amz-request-id"],
      "MaxAgeSeconds": 3600
    }
  ]
}

To retrieve the current CORS configuration:

aws s3api get-bucket-cors --bucket my-bucket

To delete CORS configuration:

aws s3api delete-bucket-cors --bucket my-bucket

Verification – Use curl with the -H option to simulate a cross-origin request:

curl -H "Origin: https://www.example.com" -H "Access-Control-Request-Method: GET" -X OPTIONS -I https://my-bucket.s3.amazonaws.com/my-object

Check the response headers for Access-Control-Allow-Origin.

CloudFront – When using CloudFront with an S3 origin, CORS configuration can be set either at the S3 bucket level or at the CloudFront distribution level using custom headers. However, the recommended approach is to configure CORS at the S3 bucket and let CloudFront forward the Origin header. If CloudFront caches responses, it must be configured to cache based on the Origin header to avoid serving a cached response from one origin to another. This is done by setting the cache policy to include the Origin header in the cache key.

API Gateway – For REST APIs, CORS must be enabled on the API Gateway resource. The exam often tests the difference between enabling CORS via the console (which creates an OPTIONS method) versus manually adding headers in integration responses.

Lambda@Edge – Can be used to modify CORS headers dynamically at CloudFront edge locations.

Scenario 1: Single-Page Application (SPA) Hosted on S3 with API Backend A company hosts a React SPA on S3 static website hosting (https://myapp.s3-website-us-east-1.amazonaws.com). The SPA makes AJAX calls to a REST API hosted on API Gateway (https://api.example.com). The API Gateway must have CORS enabled. The S3 bucket itself does not need CORS for this scenario because the SPA's JavaScript code is loaded from S3, but the actual API calls go to API Gateway. However, if the SPA also loads assets (images, fonts) from a different S3 bucket, that bucket needs CORS rules. The developer configures CORS on the asset bucket with AllowedOrigins: ["https://myapp.s3-website-us-east-1.amazonaws.com"] and AllowedMethods: ["GET", "HEAD"]. In production, they use CloudFront with custom domain to avoid the S3 website endpoint origin issue.

Scenario 2: Media Hosting for Multiple Domains A media company hosts video thumbnails in an S3 bucket and serves them to multiple partner websites (e.g., partner1.com, partner2.com). The bucket CORS configuration includes both origins in AllowedOrigins. They also expose custom headers like x-amz-meta-* for metadata. They set MaxAgeSeconds: 86400 to reduce preflight requests. Misconfiguration occurs when a partner uses a subdomain (sub.partner1.com) that is not explicitly listed; the browser blocks the request. The fix is to use a wildcard pattern like https://*.partner1.com if all subdomains are trusted, or list each subdomain explicitly.

Scenario 3: CloudFront with Custom Origin A company uses CloudFront to accelerate content delivery from an S3 bucket. The S3 bucket is configured as an origin with CORS enabled. CloudFront must forward the Origin header to S3; otherwise, CloudFront might cache a response for one origin and serve it to another. The developer sets a cache policy that includes the Origin header in the cache key. They also set MaxAgeSeconds on the S3 CORS rule to 3600. Common mistake: forgetting to forward the Origin header, leading to intermittent CORS errors when CloudFront serves cached responses without CORS headers. Debugging involves checking CloudFront logs and S3 access logs to see if the Origin header is present.