Deep Dive: Cross Origin Resource Sharing (CORS)

A deep dive guide on what Cross Origin Resource Sharing (CORS) is and how to use it.

What is CORS?

Cross Origin Resource Sharing (CORS) is a technology used by web browsers that allows one web address’s origin to access resources located at a different origin.

To understand CORS and its purpose, first we need to understand the same-origin policy, or SOP.

What is Same-Origin policy?

When a web browser loads a website, it uses the same-origin policy. This rule is a security mechanism that ensures that web addresses can only request data from other web addresses with the same origin. CORS allows for the bypass of SOP, therefore allowing web addresses to request data from different origins.

Same-origin rule was implemented in the early 2000s as a security mechanism designed to protect websites against a vulnerability that allowed for browser cookies to be manipulated and used to make requests from one website to another illicitly.

What is an Origin?

A website’s origin is defined by a combination of the protocol, domain, and port of the web address URL.

The protocol is used for defining the method used for data exchange. The domain, or hostname, is the web address’s unique identifier. The port, which is typically not visible in the URL when accessed via a web browser, defines the connection port that data is exchanged through.

Simple-origin rule requires that web addresses have the same origin, meaning that the protocol, domain, and port must all match for data to be exchanged. Cross-origin rule allows for data to be exchanged between websites that don’t have matching protocols, domains, or ports.

What is an HTTP request?

HTTP requests are methods using code to talk to a server. An HTTP request includes the request headers, request method, and a message, if any. There are several types of request methods, each with a different request for the server.

• get: Retrieves a data file from the server.

• head: Retrieves just the headers of a data file from the server.

• post: Uploads or send a data file to the server.

• put: Uploads or sends a data file to the server that overwrites something else on the server.

• delete: Deletes a data file from the server.

• patch: Changes a data file on the server.

• options: Checks the options set for the server.

• trace: Tracks requests and changes to the server.

Why Use CORS?

Sometimes, websites or applications need to access data from different origins. CORS acts as the secure, established method to share resources between websites.

Web browsers use and allow HTTP requests such as head, get, and post without requiring any CORS rules to be in place. For example, embedded images from other websites use a get request to pull the data from the other website’s origin.

Some data or assets can’t be accessed with simple HTTP requests and require CORS rules to be configured to allow access.

How does CORS work?

CORS works through rules, which you can configure and set yourself to determine which origins are allowed to bypass the same-origin rule so that data can be exchanged between them.

CORS handles two types of requests, simple requests and more complex pre-flighted requests.

Simple Requests

First request - Resource access:

Simple requests handled through CORS are either GET or POST requests from the website of one origin trying to access the web address of a second origin to access the resources stored at the second origin.

During this request, the web browser automatically sets the CORS request headers. It typically contains a set of certain, standardized HTTP headers.

When a server receives the CORS request and processes it, it will send back a set of CORS response headers along with the requested resources. These response headers include values that specify whether the current website is allowed access to the requested resources.

If the web browser is unable to see if the CORS request has been satisfied by the response headers, it is prevented from accessing the requested content.

Pre-flighted Requests

First Request - Pre-flight:

Second Request - Resource Access:

Pre-flight requests are for more complex CORS communications between a web browser and a CORS origin. A pre-flight request is required before access to resources is granted. CORS requests that are not GET or POST methods, or using non-standard HTTP headers (even with a GET or POST request), require a pre-flight request.

When a pre-flight request is required, the browser sends a request using the HTTP options method to the server that has the intended CORS request headers. The server processes the CORS request headers and responds with the request headers but the response does not contain any actual content data.

The browser then checks the response headers to confirm that the CORS request is allowed. If the browser confirms that the resource request has been allowed by the server, it makes a second request with the intended HTTP method for the actual content data, using the same CORS request headers.

CORS Rules

Elements

The following are required elements of all CORS rules:

corsRuleName

A name for your CORS rule

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.

allowedMethod element

The allowedMethod element refers to the allowed HTTP request methods you want to allow. You can specify the following values for the allowedMethod element.

• get

• put

• post

• delete

• head

The following are optional elements for CORS rules:

allowedHeader element

The allowedHeader element specifies which headers are allowed in a pref-light 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 rule. Amazon S3 will send only the allowed headers in a response that was requested.

exposeHeaders

The exposeHeaders element allows for a list of headers to be exposed to the application.

maxAgeSections

The maxAgeSections element refers to the maximum number of seconds that a web browser can keep a response to a pre-flight request cached.

Creating CORS Rules

CORS rules can be a JSON or XML file, though if using AWS CLI to apply this, a .json file is required.

Example #1 JSON:

This example is a wildcard rule that allows cross-origin GET requests from all origins.

{
"CORSRules":[
    {
        "AllowedHeaders": [],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": []
    }
    ]
}

Example #1 XML:

<CORSConfiguration>
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
    </CORSRule>
</CORSConfiguration>

Example #2 JSON:

In this second example, the CORS rule allows cross-origin PUT, POST, and DELETE requests from the http://www.example.com origin, with a MaxAgeSeconds of 3000 and ExposeHeaders of x-amz-server-side-encryption, x-amz-request-id, and x-amz-id-2.

{
"CORSRules": [
    {
        "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
    }
    ]
}

Example #2 XML:

<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedMethod>DELETE</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSeconds>
<ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
<ExposeHeader>x-amz-request-id</ExposeHeader>
<ExposeHeader>x-amz-id-2</ExposeHeader>
</CORSRule>
</CORSConfiguration>

Applying a CORS rule to a Filebase bucket

To apply a CORS rule, you can use a tool such as the AWS CLI to apply the .json file you created containing the rule. For information on how to configure AWS CLI, see here.

From the command line, enter the following command to apply the CORS rule to the intended Filebase bucket:

aws --endpoint https://s3.filebase.com s3api put-bucket-cors --bucket bucket-name --cors-configuration=file://corspolicy.json

Test the CORS configuration

You can confirm that the CORS configuration for the bucket was applied successfully by using the command:

aws --endpoint https://s3.filebase.com s3api get-bucket-cors --bucket bucket-name