Implementing CORS Policies

1. The Core Problem: The Same-Origin Policy

Before we can understand CORS, we must first understand the security rule it's designed to relax: the Same-Origin Policy (SOP). The SOP is a critical security mechanism built into every modern web browser. It dictates that a script running on a web page can only make requests to a server from the same origin.

An origin is defined by the combination of three things:

1. Protocol (e.g., http, httpss)
2. Domain (e.g., api.myapp.com)
3. Port (e.g., :8000, :443)

If any of these three parts differ between the client page and the server it's trying to contact, the request is considered cross-origin.

To understand why this restriction is so vital for web security, let's watch the beginning of the following video.

As the video explains, without the SOP, a malicious website open in one browser tab could use your browser's credentials (like session cookies) to silently make requests to your bank, social media, or email in another tab, potentially stealing data or performing actions on your behalf.

But what about our legitimate use case, where a frontend at http://localhost:3000 needs to fetch data from our Django API at http://localhost:8000? This is where Cross-Origin Resource Sharing (CORS) comes in.

2. The Solution: How CORS Works

CORS is not a Django-specific feature; it's a standard mechanism built on HTTP headers that allows a server to tell a browser which origins are permitted to access its resources. The browser initiates the cross-origin request, and the server responds with specific CORS headers to indicate whether the request should be allowed.

The two most fundamental headers in this exchange are:

1. Origin (Request Header): The browser automatically adds this header to any cross-origin request, indicating where the request came from.
2. Access-Control-Allow-Origin (Response Header): The server includes this header in its response. Its value tells the browser which origins are allowed. It can be a specific origin (e.g., https://my-frontend.com) or a wildcard (*), which allows any origin.

Simple vs. Pre-flighted Requests

Not all cross-origin requests are treated equally. The CORS standard defines two types: simple requests and pre-flighted requests. Your background in designing complex systems might lead you to appreciate this distinction—it's a way of minimizing overhead for "safe" requests while adding a layer of verification for potentially "unsafe" ones.

To dig into the mechanics of this, please study the following material.

To summarize the key points from the reading:

Simple Requests:
A request is "simple" if it meets all these conditions:

• Method is GET, HEAD, or POST.
• It includes only a few specific, "safe" headers.
• The Content-Type for POST requests is limited to application/x-www-form-urlencoded, multipart/form-data, or text/plain.

For a simple request, the browser sends the request directly, and if the server responds with a matching Access-Control-Allow-Origin header, the browser allows the JavaScript code to read the response.

Pre-flighted Requests:
Any request that doesn't meet the "simple" criteria is pre-flighted. This is common for modern APIs that use:

• Methods like PUT, PATCH, or DELETE.
• A Content-Type of application/json.
• Custom headers, like Authorization for token-based authentication.

The "pre-flight" is an automatic, preliminary OPTIONS request that the browser sends to the server to ask for permission before sending the actual request. This OPTIONS request includes headers like Access-Control-Request-Method and Access-Control-Request-Headers. The server then responds with headers like Access-Control-Allow-Methods and Access-Control-Allow-Headers to indicate what it will accept. If the server's response approves the pre-flight check, the browser then sends the actual PUT or POST request.

3. Implementing CORS in Django

Now let's move from theory to practice. If you try to connect a separate frontend application to your DRF API, you will see a CORS error in your browser's developer console. We need to configure our Django server to send the correct CORS headers.

The standard way to do this in the Django ecosystem is with a package called django-cors-headers. This package provides a middleware that automatically adds the appropriate headers to your API's responses.

The following video provides a perfect, practical walkthrough of encountering the CORS error and fixing it.

Let's break down the configuration steps shown in the video into a clear, referenceable list.

Configuration Steps

1. Install the package:

   pip install django-cors-headers
   

2. Add corsheaders to INSTALLED_APPS in settings.py:
   Make sure to add it to your list of installed applications so Django knows about it.

   # settings.py
   INSTALLED_APPS = [
       # ... other apps
       'corsheaders',
       'rest_framework',
       # ...
   ]
   

3. Add the CorsMiddleware to your MIDDLEWARE list in settings.py:
   Its position is important. It should be placed as high as possible, especially before any middleware that can generate responses, like Django's CommonMiddleware.

   # settings.py
   MIDDLEWARE = [
       'django.middleware.security.SecurityMiddleware',
       'django.contrib.sessions.middleware.SessionMiddleware',
       'corsheaders.middleware.CorsMiddleware', # Add this
       'django.middleware.common.CommonMiddleware',
       'django.middleware.csrf.CsrfViewMiddleware',
       'django.contrib.auth.middleware.AuthenticationMiddleware',
       'django.contrib.messages.middleware.MessageMiddleware',
       'django.middleware.clickjacking.XFrameOptionsMiddleware',
   ]
   

4. Configure the allowed origins:
   This is the most critical step. You need to tell the middleware which frontend origins are allowed to make requests. The recommended setting for this is CORS_ALLOWED_ORIGINS.

   # settings.py
   
   # This should be a list of strings representing the origins
   # that are allowed to make cross-site HTTP requests.
   CORS_ALLOWED_ORIGINS = [
       "http://localhost:3000",      # The origin for your React/Vue dev server
       "http://127.0.0.1:3000",
       "https://my-frontend-app.com", # The origin for your production frontend
   ]
   

   For development, you'll typically add localhost and 127.0.0.1 with the port your frontend development server uses. For production, you'll add the actual domain of your deployed frontend.

Other Configuration Options

While CORS_ALLOWED_ORIGINS is the main setting you'll use, it's good to be aware of a few others:

• CORS_ORIGIN_ALLOW_ALL: Setting this to True will allow requests from any origin. This can be useful for fully public APIs but is generally a security risk and should be avoided for applications that handle sensitive data.
• CORS_ALLOW_CREDENTIALS: Set this to True if you need to allow cross-origin requests to include cookies. When this is True, you cannot use a wildcard (*) for CORS_ALLOWED_ORIGINS.
• CORS_ALLOW_METHODS: A list of HTTP methods that are allowed, e.g., ['GET', 'POST', 'PUT'].
• CORS_ALLOW_HEADERS: A list of non-standard HTTP headers that are allowed, e.g., ['authorization', 'content-type'].

For most use cases, django-cors-headers handles the allowed methods and headers automatically, so you often only need to specify the origins.

Conclusion

In this lesson, we demystified CORS by tracing it back to its root cause: the browser's Same-Origin Policy. By understanding the problem, the solution—a negotiation via HTTP headers—becomes much clearer. You now have both the theoretical knowledge and the practical steps needed to correctly configure your Django API to communicate securely with frontend applications hosted on different domains.

Key Takeaways:

• The Same-Origin Policy (SOP) is a browser security feature that restricts scripts on one origin from accessing resources on another.
• CORS is the W3C standard that allows servers to relax the SOP in a controlled way using special HTTP headers.
• Browsers automatically handle CORS by sending an Origin header and, for complex requests, a pre-flight OPTIONS request.
• The server must respond with an Access-Control-Allow-Origin header and other related headers to grant permission.
• In Django, the django-cors-headers package is the standard tool to manage this. The primary configuration involves adding its middleware and defining a whitelist of trusted origins in CORS_ALLOWED_ORIGINS.

Preview of the Next Lesson:
We've now controlled who can access our API from the browser. Next, we'll look at controlling how much they can access it. In the upcoming lesson, we will apply rate limiting to API endpoints to prevent abuse and ensure service stability.