The principles of Cross-Origin Resource Sharing (CORS)

By | April 30, 2015

Here we are going to learn the techniques used to enable Cross-domain resource sharing known as CORS. I thought of this when I wanted to develop my first open source API where I wanted to make using the API as simple as possible for the developers that are going to be using it. I felt the simplest way was to just make my developers include just a script tag. Then I remembered the same-origin policy which will not allow an AJAX call to an external domain. The savior of developers in this respect CORS. So I am going to take us through the basic principles of Cross-Origin Resource Sharing (CORS).

Why is CORS important?

JavaScript and the web programming has grown by leaps and bounds over the years, but the same-origin policy still remains. This prevents JavaScript from making requests across domain boundaries, and has spawned various hacks for making cross-domain requests.

CORS introduces a standard mechanism that can be used by all browsers for implementing cross-domain requests. The spec defines a set of headers that allow the browser and server to communicate about which requests are (and are not) allowed. CORS continues the spirit of the open web by bringing API access to all.

From enable-cors.org

How to use CORS

CORS is best used with XMLHttpRequest2 object or the equivalent XDomainRequest object on Internet Explorer which has the following browser compatibility.

  • Chrome 3+
  • Firefox 3.5+
  • Opera 12+
  • Safari 4+
  • Internet Explorer 8+

To get started, you will first need to create the appropriate request object.

The XMLHttpRequest2 events

Unlike the XMLHttpRequest object which only has the onreadestatechange event, the XMLHttpRequest2 object comes with a new useful set of events. The events are listed below:

  • onload – Fires when the request is completed
  • onprogress – Fires when the object is loading and sending data
  • ontimeout – Fires when the request times out
  • onerror – Fires when the request fails
  • onloadstart(Not supported with XDomainRequest of IE) – Fires when the request starts
  • onloadend(Not supported with XDomainRequest of IE) – Fires when the requested is completed, whether it is successful or it fails
  • onabort(Not supported with XDomainRequest of IE) – Fires when the request is aborted

Source: XMLHttpRequest events

Example of onload and onerror events. But the onerror does not provide details about the error encountered.

How to implement CORS Server

The above XMLHttpRequest2 object supports CORS requests, however the server will still reject the requests if there is not server-side implementation to support CORS. Here is the idea; the server has to declare a resource accessible by an external domain by sending some headers.

All CORS related headers are prefixed with Access-Control-. There are few headers that are used when implementing CORS but the major one which is usually okay if you do not have other options to set is to set the Access-Control-Allow-Origin: header.

Example:

In the above exmaple the Access-Control-Allow-Origin header is set to the domain that is making the request if you want to support a particular list of domains or simply set to * to support all domains.

To know the origin that is making the request you check for the Origin header. If this header is not set for the request the CORS will fail.

Here is an example of headers set to during a CORS request from the client.

Note: to use the Access-Control-Allow-Credentials: true set in the response headers above, the xhr object has to have its withCredentials set to true. Example:

If you do not need this function in your request do not set it to false. Just simply not set it. If a value different from the one set from the request is different found in the response, the request will fail and vice – versa.

How to set the headers

Full details on how to set headers on different servers can be found on http://enable-cors.org/server.html.

But if you use PHP this can easily be don by:

Note: the header has to be set before any output of text is made to the browser to avoid the error ‘headers already sent’.

CORS with JQuery

The JQuery AJAX method $.ajax can simply be used for CORS requests but it does not support the XDomainRequest on IE. However there some JQuery plugins that provide the support.

Using JQuery, CORS support can be checked with the JQuery’s $.support.cors method which returns true if the browser supports Cors and false if otherwise. If this test is performed on IE, the method returns false.

Example of a simple CORS request with JQuery’s $.ajax method:

I hope this helps someone get started using CORS. Please comment below your opinions, findings, and queries.

Other resources to read on CORS

http://stackoverflow.com/questions/11997256/call-a-external-web-page-cross-domain-with-javascript

JQuery-ajax-cross-domain

http://enable-cors.org/server.html

http://www.nczonline.net/blog/2010/05/25/cross-domain-ajax-with-cross-origin-resource-sharing/

Leave a Reply

Your email address will not be published. Required fields are marked *