Writing on the principles & practice of building digital products

A simple guide to CORS

The "if-your-name's-not-down-you're-not-coming-in" of Javascript errors. What it means, and how to fix it.

Like an annoying younger sibling who keeps asking 'why' to every answer you give them, the "cross origin request blocked" error has been the bane of many a web developer.

In a nutshell you see this error when a server receives a request for a resource from another server asynchronously, but isn't configured to allow this to happen. A common example is trying to access a JSON file (the resource) on a different server via an Ajax request. But the resource doesn’t need to be a JSON file - it could be an image, a font, whatever really.

What this error means is that, as far as the server is concerned, your name is not on the guest list. To a server, it's guest list is it's Cross Origin Request Security (CORS) configuration. So to allow your application to access the server, you need to get your name (or in this case domain name) onto the list.

This is accomplished by setting the Access-Control-Allow-Origin headers. The specifics of how you set these headers depends on the server setup you're using. I've assumed you're using an Apache server in these examples but there's a nifty guide for other setups at Enable CORS.

On Apache, you'll need to start by making sure the module mod_headers is enabled. The process for doing this is slightly different for various operating systems, and has been answered with grace and civility over on Stack Overflow

So, assuming mod_headers is installed, let's jump in with an example. Let’s say you want to allow the domain http://animade.tv access to your server. To do this, you would add the following to your .htaccess file:

Access-Control-Allow-Origin: http://animade.tv

This effectively puts the domain http://animade.tv on the server’s guest list (i.e. It’s CORS configuration). However if you were feeling a bit more devil-may-care and wanted to throw the doors open and let any old domain in, you could use the * wildcard:

Access-Control-Allow-Origin: *

In many cases, particularly for smaller sites, this is fine. But for larger sites or where security is more of a concern you should probably limit access to the domains you will actually be using and not let any old joker in.

In addition to allowing access, the CORS configuration can also stipulate what people can do once they’re inside. Think of it like limiting people to certain areas (regular, VIP etc), but instead of areas it's HTTP methods. This is accomplished by setting the Access-Control-Allow-Methods header. So for example, if you wanted to only allow GET and POST requests, you would set the header as follows:

Access-Control-Allow-Methods: GET,POST

There's a lot to know about Access Control headers, but hopefully this will be enough of a reference for most people to get going/unstuck. If you want to get deeper into this stuff there's a good article over on Mozilla Developer Network which covers all this and a great deal more.