CORS Explained

Introduction

Cross-Origin Resource Sharing (CORS) is a security feature implemented by web browsers to regulate web requests originating from different origins. Understanding CORS is crucial for any engineering team that is building web services, APIs, or web-based applications that interact over HTTP(S). This handbook page aims to provide a concise yet comprehensive overview of CORS, why it matters, and how to deal with CORS issues in development and production.

What Is CORS?

CORS stands for Cross-Origin Resource Sharing. It’s a protocol that enables secure cross-origin requests, allowing web servers to declare who can and cannot access a resource from a different origin. An origin is defined as the combination of a scheme (e.g., HTTP or HTTPS), a domain, and a port.

Why Does CORS Matter?

Web browsers enforce a security measure known as the Same-Origin Policy (SOP), which restricts web pages from making requests to a different domain than the one that served the web page. While this policy helps to prevent a range of security issues, it poses a problem when you need to fetch data from different origins for legitimate purposes. CORS serves as a controlled relaxation of the same-origin restrictions.

How Does CORS Work?

When a request is made to a different origin, the browser automatically attaches an Origin header to it. The server can then decide whether to permit or deny the request based on its CORS policy. If permitted, the server responds with appropriate CORS headers (such as Access-Control-Allow-Origin), instructing the browser to allow the request.

Simple vs Preflight Requests

Simple Requests: These are requests that meet certain criteria (like using GET, POST, or HEAD methods) and are less likely to pose a risk. In this case, the browser sends the request with an Origin header, and expects the server to include CORS headers in the response.
Preflight Requests: For more complex requests (e.g., requests with methods other than GET, POST, or HEAD, or custom headers), the browser sends a preliminary “preflight” request using the OPTIONS method. This preflight checks the server’s CORS policy to see if the actual request is allowed.

Implementing CORS in Your Projects

Frontend

No specific changes are typically required in frontend code to support CORS. The browser handles CORS automatically. However, you can set the credentials property in your fetch or XMLHttpRequest to include cookies and credentials:

fetch(url, {
  credentials: 'include'
});

Backend

Node.js with Express

const cors = require('cors');

const app = express();

app.use(cors({
  origin: 'http://your-app-origin.com'
}));

Django

In settings.py:

INSTALLED_APPS = [
    ...
    'corsheaders',
    ...
]

MIDDLEWARE = [
    ...
    'corsheaders.middleware.CorsMiddleware',
    ...
]

CORS_ALLOWED_ORIGINS = [
    "http://your-app-origin.com",
]

Flask

from flask import Flask
from flask_cors import CORS

app = Flask(__name__)
CORS(app, resources={r"/api/*": {"origins": "http://your-app-origin.com"}})

Common Pitfalls and Debugging

No ‘Access-Control-Allow-Origin’ header: This is the most common error. Check whether the server configuration is set up to return the appropriate CORS headers.
CORS Preflight Did Not Succeed: This usually means the preflight request was rejected. Check your server’s OPTIONS method and CORS policy.
Cookies Not Being Sent: Ensure you’ve configured CORS to handle credentials.