Understanding and Implementing CORS

The "Why": Understanding 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). This is a critical security mechanism built into every modern web browser.

Let's start by reading a clear definition of what constitutes an "origin" and the security risks that led to the creation of the SOP.

As the article explained, the Same-Origin Policy is your browser's first line of defense against a whole class of web attacks.

To summarize:

• An origin is defined by the combination of scheme (e.g., http), hostname (e.g., www.example.com), and port (e.g., 80). If any of these differ, it's a different origin.
• The Problem: Without the SOP, a script running on evil-site.com could make a fetch() request to your-bank.com/api/transfer. If you were logged into your bank, your browser would automatically attach your session cookies to that request, potentially allowing the malicious script to initiate a transaction on your behalf.
• The Solution (SOP): The browser enforces a simple rule: a script loaded from one origin is prohibited from reading the response of a request made to a different origin.

The SOP is very restrictive, and for good reason. But what happens when you intentionally build your application with a separate frontend and backend origin? You need a way to tell the browser, "It's okay, I trust this cross-origin request." That is precisely what CORS is for.

The "What": Cross-Origin Resource Sharing (CORS)

CORS is not a security feature that protects your server. Instead, CORS is a mechanism that allows a server to tell a browser that it is safe to allow a cross-origin request. The enforcement happens entirely within the browser.

This mechanism works through a standardized exchange of HTTP headers. The following short video gives a great high-level overview.

Now that we have the general idea, let's dive into the technical specifics of how this header exchange works. CORS divides requests into two categories: simple requests and preflighted requests.

The "How" Part 1: Simple Requests

A "simple request" is one that is considered low-risk because it resembles the kind of requests that could be made by old HTML <form> tags, which predate these security policies.

Let's turn to the MDN Web Docs, the definitive reference for web standards, for a precise definition of what qualifies as a simple request.

So, if a request meets these criteria (e.g., a GET request with no custom headers), the flow is straightforward:

1. The browser sends the GET request to the cross-origin server, automatically adding an Origin header (e.g., Origin: https://app.mycompany.com).
2. The server checks the Origin header against its list of allowed origins.
3. If the origin is permitted, the server processes the request and includes the header Access-Control-Allow-Origin: https://app.mycompany.com in its response.
4. The browser receives the response, sees the matching Access-Control-Allow-Origin header, and allows your JavaScript code to access the response data. If the header is missing or doesn't match, the browser blocks the response and logs a CORS error to the console.

Now, let's see this in action. The following video demonstrates this exact process by building a simple Python web server from scratch. This should resonate with your background and goal of understanding things from the root.

The "How" Part 2: Preflighted Requests

What happens if your request doesn't meet the "simple" criteria? For example, what if you want to send a DELETE request, or a POST request with a JSON body (Content-Type: application/json), or include an Authorization header with a token?

For these more "complex" or potentially destructive requests, the browser takes an extra safety step: it sends a preflight request.

A preflight is a preliminary check, using the OPTIONS HTTP method, that the browser sends before the actual request. It's like asking for permission: "Hey server, I'm about to send a DELETE request from this origin with a custom Authorization header. Is that okay with you?"

This two-step process is crucial for security.

Let's go back to the MDN documentation for a formal breakdown of the preflight mechanism and the headers involved.

The preflight flow looks like this:

1. Preflight Request (OPTIONS): The browser sends an OPTIONS request with:
   • Origin: https://app.mycompany.com
   • Access-Control-Request-Method: POST
   • Access-Control-Request-Headers: Content-Type, Authorization
2. Preflight Response: The server, if configured to allow this, responds with 204 No Content and headers like:
   • Access-Control-Allow-Origin: https://app.mycompany.com
   • Access-Control-Allow-Methods: GET, POST, OPTIONS
   • Access-Control-Allow-Headers: Content-Type, Authorization
   • Access-Control-Max-Age: 86400 (caches the preflight result for 24 hours)
3. Actual Request: If the preflight response was permissive, the browser then sends the actual POST request with the JSON body and Authorization header. The server's response to this request must also include Access-Control-Allow-Origin for the browser to expose the response data.

Let's see the practical side of this. We'll finish the video from Hussein Nasser, where he implements the OPTIONS handler in his Python server to fix a preflight error.

Configuring CORS in a Django Backend

Building a server from scratch is a great way to learn the fundamentals. In a real-world Django application, you won't be handling these headers manually in every view. Instead, you'll use a middleware that intercepts all requests and responses to apply your CORS rules globally.

The most popular library for this is django-cors-headers. It works by adding a middleware to your Django settings that checks incoming requests and adds the correct CORS headers to outgoing responses based on your configuration.

Common settings include:

• CORS_ALLOWED_ORIGINS: A list of origins that are authorized to make cross-site HTTP requests. This is the most secure and recommended setting.
  • Example: CORS_ALLOWED_ORIGINS = ["https://app.mycompany.com", "https://admin.mycompany.com"]
• CORS_ALLOW_ALL_ORIGINS: If set to True, this will allow all origins (Access-Control-Allow-Origin: *). This is acceptable for public APIs that don't use credentials like cookies, but it's insecure otherwise.
• CORS_ALLOW_METHODS: A list of HTTP verbs that are allowed, e.g., ['DELETE', 'GET', 'POST', 'PUT'].
• CORS_ALLOW_HEADERS: A list of non-standard HTTP headers that are allowed, like authorization.
• CORS_ALLOW_CREDENTIALS: If set to True, this allows cookies to be included in cross-origin requests. Crucially, if you enable this, you cannot set CORS_ALLOW_ALL_ORIGINS to True. You must explicitly list the allowed origins. This is a strict browser security rule.

For a deeper look into these configurations and other best practices, the following reading is highly recommended.

Conclusion

CORS is often a source of frustration for new developers, but as we've seen, it's a logical and necessary part of the web's security model. By understanding its foundation in the Same-Origin Policy, you can work with the browser's security features, not against them.

Key Takeaways:

• The Same-Origin Policy (SOP) is a browser security feature that blocks scripts from reading responses from a different origin.
• CORS is the mechanism that servers use to tell browsers it's safe to relax the SOP for specific origins, methods, and headers.
• CORS operates through a system of HTTP headers, primarily Origin from the client and Access-Control-Allow-* from the server.
• Simple requests (like GET) are checked when the response arrives.
• Preflighted requests (like PUT or requests with custom headers) require a preliminary OPTIONS request to get permission from the server before the actual request is sent.
• As a backend developer, you will configure CORS via middleware, defining a clear policy of which origins are trusted.

Preview of the Next Lesson:

In this module, we've dissected the anatomy of HTTP, from its structure and methods to its evolution and security policies like CORS. The final piece of the puzzle is to learn how to observe and debug this traffic directly. In the next lesson, we will get hands-on and learn how to inspect and debug HTTP traffic using curl and browser developer tools, putting all the theory from this module into practice.