# Using cross-origin resource sharing (CORS) Cross-origin resource sharing (CORS) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. With CORS support, you can build rich client-side web applications with Amazon S3 and selectively allow cross-origin access to your Amazon S3 resources. This section provides an overview of CORS. The subtopics describe how you can enable CORS using the Amazon S3 console, or programmatically by using the Amazon S3 REST API and the AWS SDKs. ## Cross-origin resource sharing: Use-case scenarios The following are example scenarios for using CORS. **Scenario 1** Suppose that you are hosting a website in an Amazon S3 bucket named `website` as described in [Hosting a static website using Amazon S3](WebsiteHosting.md). Your users load the website endpoint: ``` http://website.s3-website.us-east-1.amazonaws.com ``` Now you want to use JavaScript on the webpages that are stored in this bucket to be able to make authenticated GET and PUT requests against the same bucket by using the Amazon S3 API endpoint for the bucket, `website.s3.us-east-1.amazonaws.com`. A browser would normally block JavaScript from allowing those requests, but with CORS you can configure your bucket to explicitly enable cross-origin requests from `website.s3-website.us-east-1.amazonaws.com`. **Scenario 2** Suppose that you want to host a web font from your S3 bucket. Again, browsers require a CORS check (also called a preflight check) for loading web fonts. You would configure the bucket that is hosting the web font to allow any origin to make these requests. ## How does Amazon S3 evaluate the CORS configuration on a bucket? When Amazon S3 receives a preflight request from a browser, it evaluates the CORS configuration for the bucket and uses the first `CORSRule` rule that matches the incoming browser request to enable a cross-origin request. For a rule to match, the following conditions must be met: + The `Origin` header in a CORS request to your bucket must match the origins in the `AllowedOrigins` element in your CORS configuration. + The HTTP methods that are specified in the `Access-Control-Request-Method` in a CORS request to your bucket must match the method or methods listed in the `AllowedMethods` element in your CORS configuration. + The headers listed in the `Access-Control-Request-Headers` header in a pre-flight request must match the headers in the `AllowedHeaders` element in your CORS configuration. **Note** The ACLs and policies continue to apply when you enable CORS on your bucket. ## How Object Lambda Access Point supports CORS When S3 Object Lambda receives a request from a browser or the request includes an `Origin` header, S3 Object Lambda always adds an `"AllowedOrigins":"*"` header field. For more information about using CORS, see the following topics. **Topics** + [ ## Cross-origin resource sharing: Use-case scenarios ](#example-scenarios-cors) + [ ## How does Amazon S3 evaluate the CORS configuration on a bucket? ](#cors-eval-criteria) + [ ## How Object Lambda Access Point supports CORS ](#cors-olap-cors) + [ # Elements of a CORS configuration ](ManageCorsUsing.md) + [ # Configuring cross-origin resource sharing (CORS) ](enabling-cors-examples.md) + [ # Testing CORS ](testing-cors.md) + [ # Troubleshooting CORS ](cors-troubleshooting.md) # Elements of a CORS configuration To configure your bucket to allow cross-origin requests, you create a CORS configuration. The CORS configuration is a document with elements that identify the origins that you will allow to access your bucket, the operations (HTTP methods) that you will support for each origin, and other operation-specific information. You can add up to 100 rules to the configuration. You can add the CORS configuration as the `cors` subresource to the bucket. If you are configuring CORS in the S3 console, you must use JSON to create a CORS configuration. The new S3 console only supports JSON CORS configurations. For more information about the CORS configuration and the elements in it, see the topics below. For instructions on how to add a CORS configuration, see [Configuring cross-origin resource sharing (CORS)](enabling-cors-examples.md). **Important** In the S3 console, the CORS configuration must be JSON. **Topics** + [ ## `AllowedMethods` element ](#cors-allowed-methods) + [ ## `AllowedOrigins` element ](#cors-allowed-origin) + [ ## `AllowedHeaders` element ](#cors-allowed-headers) + [ ## `ExposeHeaders` element ](#cors-expose-headers) + [ ## `MaxAgeSeconds` element ](#cors-max-age) + [ ## Examples of CORS configurations ](#cors-example-1) ## `AllowedMethods` element In the CORS configuration, you can specify the following values for the `AllowedMethods` element. + GET + PUT + POST + DELETE + HEAD ## `AllowedOrigins` element In the `AllowedOrigins` element, you specify the origins that you want to allow cross-domain requests from, for example,` http://www.example.com`. The origin string can contain only one `*` wildcard character, such as `http://*.example.com`. You can optionally specify `*` as the origin to enable all the origins to send cross-origin requests. You can also specify `https` to enable only secure origins. ## `AllowedHeaders` element The `AllowedHeaders` element specifies which headers are allowed in a preflight request through the `Access-Control-Request-Headers` header. Each header name in the `Access-Control-Request-Headers` header must match a corresponding entry in the element. Amazon S3 will send only the allowed headers in a response that were requested. For a sample list of headers that can be used in requests to Amazon S3, go to [Common Request Headers](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonRequestHeaders.html) in the *Amazon Simple Storage Service API Reference* guide. Each AllowedHeaders string in your configuration can contain at most one \$1 wildcard character. For example, `x-amz-*` will enable all Amazon-specific headers. ## `ExposeHeaders` element Each `ExposeHeader` element identifies a header in the response that you want customers to be able to access from their applications (for example, from a JavaScript `XMLHttpRequest` object). For a list of common Amazon S3 response headers, go to [Common Response Headers](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html) in the *Amazon Simple Storage Service API Reference* guide. ## `MaxAgeSeconds` element The `MaxAgeSeconds` element specifies the time in seconds that your browser can cache the response for a preflight request as identified by the resource, the HTTP method, and the origin. ## Examples of CORS configurations Instead of accessing a website by using an Amazon S3 website endpoint, you can use your own domain, such as `example1.com` to serve your content. For information about using your own domain, see [Tutorial: Configuring a static website using a custom domain registered with Route 53](website-hosting-custom-domain-walkthrough.md). The following example CORS configuration has three rules, which are specified as `CORSRule` elements: + The first rule allows cross-origin PUT, POST, and DELETE requests from the `http://www.example1.com` origin. The rule also allows all headers in a preflight OPTIONS request through the `Access-Control-Request-Headers` header. In response to preflight OPTIONS requests, Amazon S3 returns requested headers. + The second rule allows the same cross-origin requests as the first rule, but the rule applies to another origin, `http://www.example2.com`. + The third rule allows cross-origin GET requests from all origins. The `*` wildcard character refers to all origins. ------ #### [ JSON ] ``` [ { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "PUT", "POST", "DELETE" ], "AllowedOrigins": [ "http://www.example1.com" ], "ExposeHeaders": [] }, { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "PUT", "POST", "DELETE" ], "AllowedOrigins": [ "http://www.example2.com" ], "ExposeHeaders": [] }, { "AllowedHeaders": [], "AllowedMethods": [ "GET" ], "AllowedOrigins": [ "*" ], "ExposeHeaders": [] } ] ``` ------ #### [ XML ] ``` http://www.example1.com PUT POST DELETE * http://www.example2.com PUT POST DELETE * * GET ``` ------ The CORS configuration also allows optional configuration parameters, as shown in the following CORS configuration. In this example, the CORS configuration allows cross-origin PUT, POST, and DELETE requests from the `http://www.example.com` origin. ------ #### [ JSON ] ``` [ { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "PUT", "POST", "DELETE" ], "AllowedOrigins": [ "http://www.example.com" ], "ExposeHeaders": [ "x-amz-server-side-encryption", "x-amz-request-id", "x-amz-id-2" ], "MaxAgeSeconds": 3000 } ] ``` ------ #### [ XML ] ``` http://www.example.com PUT POST DELETE * 3000 x-amz-server-side-encryption x-amz-request-id x-amz-id-2 ``` ------ The `CORSRule` element in the preceding configuration includes the following optional elements: + `MaxAgeSeconds`—Specifies the amount of time in seconds (in this example, 3000) that the browser caches an Amazon S3 response to a preflight OPTIONS request for the specified resource. By caching the response, the browser does not have to send preflight requests to Amazon S3 if the original request will be repeated. + `ExposeHeaders`—Identifies the response headers (in this example, `x-amz-server-side-encryption`, `x-amz-request-id`, and `x-amz-id-2`) that customers are able to access from their applications (for example, from a JavaScript `XMLHttpRequest` object). # Configuring cross-origin resource sharing (CORS) Cross-origin resource sharing (CORS) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. With CORS support, you can build rich client-side web applications with Amazon S3 and selectively allow cross-origin access to your Amazon S3 resources. This section shows you how to enable CORS using the Amazon S3 console, the Amazon S3 REST API, and the AWS SDKs. To configure your bucket to allow cross-origin requests, you add a CORS configuration to the bucket. A CORS configuration is a document that defines rules that identify the origins that you will allow to access your bucket, the operations (HTTP methods) supported for each origin, and other operation-specific information. In the S3 console, the CORS configuration must be a JSON document. For example CORS configurations in JSON and XML, see [Elements of a CORS configuration](ManageCorsUsing.md). ## Using the S3 console This section explains how to use the Amazon S3 console to add a cross-origin resource sharing (CORS) configuration to an S3 bucket. When you enable CORS on the bucket, the access control lists (ACLs) and other access permission policies continue to apply. **Important** In the S3 console, the CORS configuration must be JSON. For examples CORS configurations in JSON and XML, see [Elements of a CORS configuration](ManageCorsUsing.md). **To add a CORS configuration to an S3 bucket** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **General purpose buckets**. 1. In the buckets list, choose the name of the bucket that you want to create a bucket policy for. 1. Choose **Permissions**. 1. In the **Cross-origin resource sharing (CORS)** section, choose **Edit**. 1. In the **CORS configuration editor** text box, type or copy and paste a new CORS configuration, or edit an existing configuration. The CORS configuration is a JSON file. The text that you type in the editor must be valid JSON. For more information, see [Elements of a CORS configuration](ManageCorsUsing.md). 1. Choose **Save changes**. **Note** Amazon S3 displays the Amazon Resource Name (ARN) for the bucket next to the **CORS configuration editor** title. For more information about ARNs, see [Amazon Resource Names (ARNs) and AWS Service Namespaces](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) in the *Amazon Web Services General Reference*. ## Using the AWS SDKs You can use the AWS SDK to manage cross-origin resource sharing (CORS) for a bucket. For more information about CORS, see [Using cross-origin resource sharing (CORS)](cors.md). The following examples: + Creates a CORS configuration and sets the configuration on a bucket + Retrieves the configuration and modifies it by adding a rule + Adds the modified configuration to the bucket + Deletes the configuration ------ #### [ Java ] **Example** **Example** For instructions on how to create and test a working sample, see [Getting Started](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/getting-started.html) in the AWS SDK for Java Developer Guide. ``` import com.amazonaws.AmazonServiceException; import com.amazonaws.SdkClientException; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.regions.Regions; import com.amazonaws.services.s3.AmazonS3; import com.amazonaws.services.s3.AmazonS3ClientBuilder; import com.amazonaws.services.s3.model.BucketCrossOriginConfiguration; import com.amazonaws.services.s3.model.CORSRule; import java.io.IOException; import java.util.ArrayList; import java.util.Arrays; import java.util.List; public class CORS { public static void main(String[] args) throws IOException { Regions clientRegion = Regions.DEFAULT_REGION; String bucketName = "*** Bucket name ***"; // Create two CORS rules. List rule1AM = new ArrayList(); rule1AM.add(CORSRule.AllowedMethods.PUT); rule1AM.add(CORSRule.AllowedMethods.POST); rule1AM.add(CORSRule.AllowedMethods.DELETE); CORSRule rule1 = new CORSRule().withId("CORSRule1").withAllowedMethods(rule1AM) .withAllowedOrigins(Arrays.asList("http://*.example.com")); List rule2AM = new ArrayList(); rule2AM.add(CORSRule.AllowedMethods.GET); CORSRule rule2 = new CORSRule().withId("CORSRule2").withAllowedMethods(rule2AM) .withAllowedOrigins(Arrays.asList("*")).withMaxAgeSeconds(3000) .withExposedHeaders(Arrays.asList("x-amz-server-side-encryption")); List rules = new ArrayList(); rules.add(rule1); rules.add(rule2); // Add the rules to a new CORS configuration. BucketCrossOriginConfiguration configuration = new BucketCrossOriginConfiguration(); configuration.setRules(rules); try { AmazonS3 s3Client = AmazonS3ClientBuilder.standard() .withCredentials(new ProfileCredentialsProvider()) .withRegion(clientRegion) .build(); // Add the configuration to the bucket. s3Client.setBucketCrossOriginConfiguration(bucketName, configuration); // Retrieve and display the configuration. configuration = s3Client.getBucketCrossOriginConfiguration(bucketName); printCORSConfiguration(configuration); // Add another new rule. List rule3AM = new ArrayList(); rule3AM.add(CORSRule.AllowedMethods.HEAD); CORSRule rule3 = new CORSRule().withId("CORSRule3").withAllowedMethods(rule3AM) .withAllowedOrigins(Arrays.asList("http://www.example.com")); rules = configuration.getRules(); rules.add(rule3); configuration.setRules(rules); s3Client.setBucketCrossOriginConfiguration(bucketName, configuration); // Verify that the new rule was added by checking the number of rules in the // configuration. configuration = s3Client.getBucketCrossOriginConfiguration(bucketName); System.out.println("Expected # of rules = 3, found " + configuration.getRules().size()); // Delete the configuration. s3Client.deleteBucketCrossOriginConfiguration(bucketName); System.out.println("Removed CORS configuration."); // Retrieve and display the configuration to verify that it was // successfully deleted. configuration = s3Client.getBucketCrossOriginConfiguration(bucketName); printCORSConfiguration(configuration); } catch (AmazonServiceException e) { // The call was transmitted successfully, but Amazon S3 couldn't process // it, so it returned an error response. e.printStackTrace(); } catch (SdkClientException e) { // Amazon S3 couldn't be contacted for a response, or the client // couldn't parse the response from Amazon S3. e.printStackTrace(); } } private static void printCORSConfiguration(BucketCrossOriginConfiguration configuration) { if (configuration == null) { System.out.println("Configuration is null."); } else { System.out.println("Configuration has " + configuration.getRules().size() + " rules\n"); for (CORSRule rule : configuration.getRules()) { System.out.println("Rule ID: " + rule.getId()); System.out.println("MaxAgeSeconds: " + rule.getMaxAgeSeconds()); System.out.println("AllowedMethod: " + rule.getAllowedMethods()); System.out.println("AllowedOrigins: " + rule.getAllowedOrigins()); System.out.println("AllowedHeaders: " + rule.getAllowedHeaders()); System.out.println("ExposeHeader: " + rule.getExposedHeaders()); System.out.println(); } } } } ``` ------ #### [ .NET ] **Example** For information about setting up and running the code examples, see [Getting Started with the AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-setup.html) in the *AWS SDK for .NET Developer Guide*. ``` using Amazon; using Amazon.S3; using Amazon.S3.Model; using System; using System.Collections.Generic; using System.Threading.Tasks; namespace Amazon.DocSamples.S3 { class CORSTest { private const string bucketName = "*** bucket name ***"; // Specify your bucket region (an example region is shown). private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2; private static IAmazonS3 s3Client; public static void Main() { s3Client = new AmazonS3Client(bucketRegion); CORSConfigTestAsync().Wait(); } private static async Task CORSConfigTestAsync() { try { // Create a new configuration request and add two rules CORSConfiguration configuration = new CORSConfiguration { Rules = new System.Collections.Generic.List { new CORSRule { Id = "CORSRule1", AllowedMethods = new List {"PUT", "POST", "DELETE"}, AllowedOrigins = new List {"http://*.example.com"} }, new CORSRule { Id = "CORSRule2", AllowedMethods = new List {"GET"}, AllowedOrigins = new List {"*"}, MaxAgeSeconds = 3000, ExposeHeaders = new List {"x-amz-server-side-encryption"} } } }; // Add the configuration to the bucket. await PutCORSConfigurationAsync(configuration); // Retrieve an existing configuration. configuration = await RetrieveCORSConfigurationAsync(); // Add a new rule. configuration.Rules.Add(new CORSRule { Id = "CORSRule3", AllowedMethods = new List { "HEAD" }, AllowedOrigins = new List { "http://www.example.com" } }); // Add the configuration to the bucket. await PutCORSConfigurationAsync(configuration); // Verify that there are now three rules. configuration = await RetrieveCORSConfigurationAsync(); Console.WriteLine(); Console.WriteLine("Expected # of rulest=3; found:{0}", configuration.Rules.Count); Console.WriteLine(); Console.WriteLine("Pause before configuration delete. To continue, click Enter..."); Console.ReadKey(); // Delete the configuration. await DeleteCORSConfigurationAsync(); // Retrieve a nonexistent configuration. configuration = await RetrieveCORSConfigurationAsync(); } catch (AmazonS3Exception e) { Console.WriteLine("Error encountered on server. Message:'{0}' when writing an object", e.Message); } catch (Exception e) { Console.WriteLine("Unknown encountered on server. Message:'{0}' when writing an object", e.Message); } } static async Task PutCORSConfigurationAsync(CORSConfiguration configuration) { PutCORSConfigurationRequest request = new PutCORSConfigurationRequest { BucketName = bucketName, Configuration = configuration }; var response = await s3Client.PutCORSConfigurationAsync(request); } static async Task RetrieveCORSConfigurationAsync() { GetCORSConfigurationRequest request = new GetCORSConfigurationRequest { BucketName = bucketName }; var response = await s3Client.GetCORSConfigurationAsync(request); var configuration = response.Configuration; PrintCORSRules(configuration); return configuration; } static async Task DeleteCORSConfigurationAsync() { DeleteCORSConfigurationRequest request = new DeleteCORSConfigurationRequest { BucketName = bucketName }; await s3Client.DeleteCORSConfigurationAsync(request); } static void PrintCORSRules(CORSConfiguration configuration) { Console.WriteLine(); if (configuration == null) { Console.WriteLine("\nConfiguration is null"); return; } Console.WriteLine("Configuration has {0} rules:", configuration.Rules.Count); foreach (CORSRule rule in configuration.Rules) { Console.WriteLine("Rule ID: {0}", rule.Id); Console.WriteLine("MaxAgeSeconds: {0}", rule.MaxAgeSeconds); Console.WriteLine("AllowedMethod: {0}", string.Join(", ", rule.AllowedMethods.ToArray())); Console.WriteLine("AllowedOrigins: {0}", string.Join(", ", rule.AllowedOrigins.ToArray())); Console.WriteLine("AllowedHeaders: {0}", string.Join(", ", rule.AllowedHeaders.ToArray())); Console.WriteLine("ExposeHeader: {0}", string.Join(", ", rule.ExposeHeaders.ToArray())); } } } } ``` ------ ## Using the REST API To set a CORS configuration on your bucket, you can use the AWS Management Console. If your application requires it, you can also send REST requests directly. The following sections in the *Amazon Simple Storage Service API Reference* describe the REST API actions related to the CORS configuration: + [PutBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTcors.html) + [GetBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGETcors.html) + [DeleteBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketDELETEcors.html) + [OPTIONS object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTOPTIONSobject.html) # Testing CORS To test your CORS configuration, a CORS preflight request can be sent with the `OPTIONS` method so that the server can respond if it is acceptable to send the request. When Amazon S3 receives a preflight request, S3 evaluates the CORS configuration for the bucket and uses the first `CORSRule` rule that matches the incoming request to enable a cross-origin request. For a rule to match, the following conditions must be met: + The `Origin` header in a CORS request to your bucket must match the origins in the `AllowedOrigins` element in your CORS configuration. + The HTTP methods that are specified in the `Access-Control-Request-Method` in a CORS request to your bucket must match the method or methods listed in the `AllowedMethods` element in your CORS configuration. + The headers listed in the `Access-Control-Request-Headers` header in a preflight request must match the headers in the `AllowedHeaders` element in your CORS configuration. The following is an example of a CORS configuration. To create a CORS Configuration, see [Configuring CORS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html). For more examples of a CORS configuration, see [ Elements of a CORS configuration](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html). For guidance on configuring and troubleshooting CORS rules, see [How do I configure CORS in Amazon S3 and confirm the CORS rules using cURL?](https://repost.aws/knowledge-center/s3-configure-cors) in the AWS re:Post Knowledge Center. ------ #### [ JSON ] ``` [ { "AllowedHeaders": [ "Authorization" ], "AllowedMethods": [ "GET", "PUT", "POST", "DELETE" ], "AllowedOrigins": [ "http://www.example1.com" ], "ExposeHeaders": [ "x-amz-meta-custom-header" ] } ] ``` ------ To test the CORS configuration, you can send a preflight `OPTIONS` check by using the following CURL command. CURL is a command-line tool that can be used to interact with S3. For more information, see [CURL](https://curl.se/). ``` curl -v -X OPTIONS \ -H "Origin: http://www.example1.com" \ -H "Access-Control-Request-Method: PUT" \ -H "Access-Control-Request-Headers: Authorization" \ -H "Access-Control-Expose-Headers: x-amz-meta-custom-header"\ "http://bucket_name.s3.amazonaws.com/object_prefix_name" ``` In the above example, the `curl -v -x OPTIONS` command is used to send a preflight request to S3 to inquire if it is allowed by S3 to send a `PUT` request on an object from the cross origin `http://www.example1.com`. The headers `Access-Control-Request-Headers` and `Access-Control-Expose-Headers` are optional. + In response to the `Access-Control-Request-Method` header in the preflight `OPTIONS` request, Amazon S3 returns the list of allowed methods if the requested methods match. + In response to the `Access-Control-Request-Headers` header in the preflight `OPTIONS` request, Amazon S3 returns the list of allowed headers if the requested headers match. + In response to the `Access-Control-Expose-Headers` header in the preflight `OPTIONS` request, Amazon S3 returns a list of allowed headers if the requested headers match the allowed headers that can be accessed by scripts running in the browser. **Note** When sending a preflight request, if any of the CORS request headers are not allowed, none of the response CORS headers are returned. In response to this preflight `OPTIONS` request, you will receive a `200 OK` response. For common error codes received when testing CORS and more information to solve CORS related issues, see [Troubleshooting CORS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/cors-troubleshooting.html). ``` < HTTP/1.1 200 OK < Date: Fri, 12 Jul 2024 00:23:51 GMT < Access-Control-Allow-Origin: http://www.example1.com < Access-Control-Allow-Methods: GET, PUT, POST, DELETE < Access-Control-Allow-Headers: Authorization < Access-Control-Expose-Headers: x-amz-meta-custom-header < Access-Control-Allow-Credentials: true < Vary: Origin, Access-Control-Request-Headers, Access-Control-Request-Method < Server: AmazonS3 < Content-Length: 0 ``` # Troubleshooting CORS The following topics can help you troubleshoot some common CORS issues related to S3. **Topics** + [403 Forbidden error - CORS is not enabled for this bucket](#cors-not-enabled) + [403 Forbidden error - This CORS request is not allowed](#cors-not-enabled) + [ ## Headers not found in CORS response ](#Headers-not-found) + [ ## Considerations of CORS on S3 proxy integrations ](#cors-in-proxy) ## 403 Forbidden error: CORS is not enabled for this bucket The following `403 Forbidden` error occurs when a cross-origin request is sent to Amazon S3 but CORS is not configured on your S3 bucket. Error: HTTP/1.1 403 Forbidden CORS Response: CORS is not enabled for this bucket. The CORS configuration is a document or policy with rules that identify the origins that you will allow to access your bucket, the operations (HTTP methods) that you will support for each origin, and other operation-specific information. See how to [configure CORS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html) on S3 by using the Amazon S3 console, AWS SDKs, and REST API. For more information on CORS and examples of a CORS configuration, see [ Elements of CORS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html#cors-example-1). ## 403 Forbidden error: This CORS request is not allowed The following `403 Forbidden` error is received when a CORS rule in your CORS configuration doesn't match the data in your request. Error: HTTP/1.1 403 Forbidden CORS Response: This CORS request is not allowed. As a result, this `403 Forbidden` error can occur for multiple reasons: + Origin is not allowed. + Methods are not allowed. + Requested headers are not allowed. For each request that Amazon S3 receives, you must have a CORS rule in your CORS configuration that matches the data in your request. ### Origin is not allowed The `Origin` header in a CORS request to your bucket must match the origins in the `AllowedOrigins` element in your CORS configuration. A wildcard character (`"*"`) in the `AllowedOrigins` element would match all HTTP methods. For more information on how to update the `AllowedOrigins` element, see [Configuring cross-origin resource sharing (CORS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html). For example, if only the `http://www.example1.com` domain is included in the `AllowedOrigins` element, then a CORS request sent from the `http://www.example2.com` domain would receive the `403 Forbidden` error. The following example shows part of a CORS configuration that includes the `http://www.example1.com` domain in the `AllowedOrigins` element. ``` "AllowedOrigins":[ "http://www.example1.com" ] ``` For a CORS request sent from the `http://www.example2.com` domain to be successful, the `http://www.example2.com` domain should be included in the `AllowedOrigins` element of CORS configuration. ``` "AllowedOrigins":[ "http://www.example1.com" "http://www.example2.com" ] ``` ### Methods are not allowed The HTTP methods that are specified in the `Access-Control-Request-Method` in a CORS request to your bucket must match the method or methods listed in the `AllowedMethods` element in your CORS configuration. A wildcard character (`"*"`) in `AllowedMethods` would match all HTTP methods. For more information on how to update the `AllowedOrigins` element, see [Configuring cross-origin resource sharing (CORS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html). In a CORS configuration, you can specify the following methods in the `AllowedMethods` element: + `GET` + `PUT` + `POST` + `DELETE` + `HEAD` The following example shows part of a CORS configuration that includes the `GET` method in the `AllowedMethods` element. Only requests including the `GET` method would succeed. ``` "AllowedMethods":[ "GET" ] ``` If an HTTP method (for example, `PUT`) was used in a CORS request or included in a pre-flight CORS request to your bucket but the method isn't present in your CORS configuration, the request would result in a `403 Forbidden` error. To allow this CORS request or CORS pre-flight request, the `PUT` method must be added to your CORS configuration. ``` "AllowedMethods":[ "GET" "PUT" ] ``` ### Requested headers are not allowed The headers listed in the `Access-Control-Request-Headers` header in a pre-flight request must match the headers in the `AllowedHeaders` element in your CORS configuration. For a list of common headers that can be used in requests to Amazon S3, see [Common Request Headers](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonRequestHeaders.html). For more information on how to update the `AllowedHeaders` element, see [Configuring cross-origin resource sharing (CORS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html). The following example shows part of a CORS configuration that includes the `Authorization` header in the `AllowedHeaders` element. Only requests for the `Authorization` header would succeed. ``` "AllowedHeaders": [ "Authorization" ] ``` If a header (for example `Content-MD5` was included in a CORS request but the header isn't present in your CORS configuration, the request would result in a `403 Forbidden` error. To allow this CORS request , the `Content-MD5` header must be added to your CORS configuration. If you want to pass both `Authorization` and `Content-MD5` headers in a CORS request to your bucket, confirm that both headers are included in the `AllowedHeaders` element in your CORS configuration. ``` "AllowedHeaders": [ "Authorization" "Content-MD5" ] ``` ## Headers not found in CORS response The `ExposeHeaders` element in your CORS configuration identifies which response headers that you would like to make accessible to scripts and applications running in browsers, in response to a CORS request. If your objects stored in your S3 bucket have user-defined metadata (for example, `x-amz-meta-custom-header`) along with the response data, this custom header could contain additional metadata or information that you want to access from your client-side JavaScript code. However, by default, browsers block access to custom headers for security reasons. To allow your client-side JavaScript to access custom headers, you need to include the header in your CORS configuration. In the example below, the `x-amz-meta-custom-header1` header is included in the `ExposeHeaders` element. The `x-amz-meta-custom-header2` isn't included in the `ExposeHeaders` element and is missing from the CORS configuration. In the response, only the values included in the `ExposeHeaders` element would be returned. If the request included the `x-amz-meta-custom-header2` header in the `Access-Control-Expose-Headers` header, the response would still return a `200 OK`. However, only the permitted header, For example `x-amz-meta-custom-header` would be returned and show in the response. ``` "ExposeHeaders": [ "x-amz-meta-custom-header1" ] ``` To ensure all headers appear in the response, add all permitted headers to the `ExposeHeaders` element in your CORS configuration as shown below. ``` "ExposeHeaders": [ "x-amz-meta-custom-header1", "x-amz-meta-custom-header2" ] ``` ## Considerations of CORS on S3 proxy integrations If you are experiencing errors and have already checked the CORS configuration on your S3 bucket, and the cross-origin request is sent to proxies such as AWS CloudFront, try the following: + Configure the settings to allow the `OPTIONS` method for HTTP requests. + Configure the proxy to forward the following headers: `Origin`, `Access-Control-Request-Headers`, and `Access-Control-Request-Method`. + Configure the proxy settings to include the origin header in its cache key. This is important because caching proxies that don't include the origin header in their cache key may serve cached responses that don't include the appropriate CORS headers for different origins. Some proxies provide pre-defined features for CORS requests. For example, in CloudFront, you can configure a policy that includes the headers that enable cross-origin resource sharing (CORS) requests when the origin is an Amazon S3 bucket. This policy has the following settings: + Headers included in origin requests: `Origin` `Access-Control-Request-Headers` `Access-Control-Request-Method` + Cookies included in origin requests: None + Query strings included in origin requests: None For more information, see [Control origin requests with a policy](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/controlling-origin-requests.htm) and [Use managed origin request policies](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-managed-origin-request-policies.html#managed-origin-request-policy-cors-s3) in the *CloudFront Developer Guide*.