Cross-Origin Resource Sharing (CORS) is a security mechanism implemented in web browsers to control how resources (e.g., APIs, images, scripts) on one origin can be accessed by a web page from a different origin. An “origin” is defined as a combination of protocol (e.g., http or https), domain (e.g., example.com), and port (e.g., 80 or 443). CORS allows servers to specify which origins are permitted to access their resources, balancing security and functionality.

1. Why CORS Exists

Browsers enforce the Same-Origin Policy by default, which restricts web pages from making requests to a different origin than the one serving the page. This prevents malicious scripts from accessing sensitive data on other domains. However, modern web applications often need to fetch resources across origins (e.g., APIs hosted on a different domain). CORS provides a controlled way to relax the Same-Origin Policy, allowing secure cross-origin requests.

2. How CORS Works

CORS relies on HTTP headers exchanged between the client (browser) and server to determine whether a cross-origin request is allowed. The process varies depending on the type of request: simple requests or preflighted requests.

2.1 Simple Requests

A simple request meets specific criteria and does not require a preflight check. For a request to qualify as “simple,” it must:

  • Use one of these HTTP methods: GET, HEAD, or POST.
  • Only include “safe” headers like:
    • Accept
    • Accept-Language
    • Content-Language
    • Content-Type (with values application/x-www-form-urlencoded, multipart/form-data, or text/plain).
  • Not include custom headers or complex Content-Type values (e.g., application/json).

Process:

  1. The browser sends the request with an Origin header (e.g., Origin: https://client.com).
  2. The server responds with CORS headers, such as:
    • Access-Control-Allow-Origin: Specifies which origins are allowed (e.g., https://client.com or * for all origins).
    • Access-Control-Allow-Methods: Lists allowed HTTP methods (e.g., GET, POST).
    • Access-Control-Allow-Headers: Lists allowed headers.
    • Access-Control-Allow-Credentials: Indicates whether credentials (e.g., cookies) are allowed.
  3. If the server’s response permits the request (e.g., the Origin matches or * is used), the browser allows the response to be accessed by the client script. Otherwise, the browser blocks it.

2.2 Preflighted Requests

For requests that don’t meet the “simple” criteria (e.g., using PUT, DELETE, or custom headers), the browser sends a preflight request using the OPTIONS method to check if the actual request is safe.

Process:

  1. The browser sends an OPTIONS request with headers like:
    • Origin: The requesting origin.
    • Access-Control-Request-Method: The method of the actual request (e.g., PUT).
    • Access-Control-Request-Headers: Any custom headers the actual request will use.
  2. The server responds with CORS headers (e.g., Access-Control-Allow-Origin, Access-Control-Allow-Methods, etc.).
  3. If the server approves, the browser sends the actual request. If not, the browser blocks it.

2.3 Requests with Credentials

If a request includes credentials (e.g., cookies, HTTP authentication, or client-side certificates), the server must explicitly allow this by setting:

  • Access-Control-Allow-Credentials: true.
  • Access-Control-Allow-Origin must specify the exact origin (not *).

The client must also set withCredentials: true in the XMLHttpRequest or fetch API call.

3. Key CORS Headers

CORS relies on specific HTTP headers to communicate permissions. Here’s a summary:

Request Headers (Sent by Browser)

  • Origin: Indicates the origin of the client (e.g., https://client.com).
  • Access-Control-Request-Method: Used in preflight requests to indicate the method of the actual request.
  • Access-Control-Request-Headers: Used in preflight requests to list custom headers.

Response Headers (Sent by Server)

  • Access-Control-Allow-Origin: Specifies allowed origins (e.g., https://client.com or *).
  • Access-Control-Allow-Methods: Lists allowed HTTP methods (e.g., GET, POST, PUT).
  • Access-Control-Allow-Headers: Lists allowed headers (e.g., X-Custom-Header, Content-Type).
  • Access-Control-Allow-Credentials: Allows credentials if set to true.
  • Access-Control-Max-Age: Specifies how long (in seconds) the preflight response can be cached.
  • Access-Control-Expose-Headers: Lists headers the browser can expose to the client (e.g., X-Custom-Response-Header).

4. Common CORS Scenarios

4.1 Allowing All Origins

A server can allow all origins by responding with:

Access-Control-Allow-Origin: *

However, this is insecure for sensitive resources, especially if credentials are involved, as * cannot be used with Access-Control-Allow-Credentials: true.

4.2 Restricting to Specific Origins

To allow only specific origins:

Access-Control-Allow-Origin: https://client.com

The server can dynamically check the Origin header and echo it back if it’s on an allowlist.

4.3 Handling Preflight Requests

For a PUT request with a custom header:

  1. Browser sends: 
    OPTIONS /resource HTTP/1.1
Origin: https://client.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: X-Custom-Header
  2. Server responds: 
    HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://client.com
Access-Control-Allow-Methods: GET, POST, PUT
Access-Control-Allow-Headers: X-Custom-Header
Access-Control-Max-Age: 86400

4.4 Handling Credentials

For requests with cookies:

  • Client sets withCredentials: true in the request.
  • Server responds with: 
    Access-Control-Allow-Origin: https://client.com
Access-Control-Allow-Credentials: true

5. Common CORS Issues and Solutions

Issue 1: “No Access-Control-Allow-Origin Header”

  • Cause: The server didn’t include the Access-Control-Allow-Origin header.
  • Solution: Configure the server to include the appropriate header (e.g., Access-Control-Allow-Origin: * or a specific origin).

Issue 2: Preflight Request Fails

  • Cause: The server doesn’t handle OPTIONS requests or doesn’t allow the requested method/headers.
  • Solution: Ensure the server responds to OPTIONS with the correct CORS headers.

Issue 3: Credentials Fail

  • Cause: The server uses Access-Control-Allow-Origin: * with Access-Control-Allow-Credentials: true, which is invalid.
  • Solution: Specify the exact origin (e.g., https://client.com) and ensure withCredentials is set on the client.

Issue 4: Blocked by Browser

  • Cause: The browser blocks the response due to mismatched CORS policies.
  • Solution: Use browser developer tools to inspect the request/response headers and verify the server’s CORS configuration.

6. Configuring CORS on Servers

CORS is typically configured on the server side. Examples:

Node.js with Express

const express = require('express');
const app = express();

app.use((req, res, next) => {
  res.setHeader('Access-Control-Allow-Origin', 'https://client.com');
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
  if (req.method === 'OPTIONS') {
    return res.sendStatus(204);
  }
  next();
});

app.listen(3000);

Apache

Add to .htaccess or server configuration:

Header set Access-Control-Allow-Origin "https://client.com"
Header set Access-Control-Allow-Methods "GET, POST, OPTIONS"
Header set Access-Control-Allow-Headers "Content-Type"

Nginx

Add to the server block:

add_header Access-Control-Allow-Origin "https://client.com";
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
add_header Access-Control-Allow-Headers "Content-Type";
if ($request_method = 'OPTIONS') {
    return 204;
}

7. Security Considerations

  • Avoid Access-Control-Allow-Origin: * for Sensitive Data: This allows any origin to access the resource, which can lead to data exposure.
  • Validate Origins: Use an allowlist to restrict access to trusted origins.
  • Limit Methods and Headers: Only allow what’s necessary for your application.
  • Protect Credentials: Use Access-Control-Allow-Credentials cautiously and always specify an exact origin.
  • CSRF Protection: CORS doesn’t prevent Cross-Site Request Forgery (CSRF). Use CSRF tokens for sensitive operations.

8. Debugging CORS

  • Browser Developer Tools: Check the Network tab for blocked requests and inspect headers.
  • Console Errors: Look for messages like “No ‘Access-Control-Allow-Origin’ header is present.”
  • Server Logs: Verify the server is receiving and responding to OPTIONS requests correctly.
  • Tools like curl: Test server responses manually to ensure correct headers.

9. Alternatives to CORS

  • JSONP: An older technique for cross-origin requests, but it’s insecure and limited to GET requests.
  • Proxy Server: Route requests through a server on the same origin to bypass CORS, though this adds complexity.
  • Server-Side Fetch: Have your backend fetch the resource and serve it to the client.

10. Summary

CORS is a critical mechanism for enabling secure cross-origin requests in web applications. It uses HTTP headers to define access policies, with simple requests handled directly and preflighted requests requiring an OPTIONS check. Proper server configuration and careful handling of credentials are essential to avoid issues and maintain security. Understanding CORS headers, debugging techniques, and security best practices ensures robust cross-origin communication.

Comments