How to Enable and Configure CORS Headers in Nginx Web Server

Overview & Problem Matrix

When building decoupled modern application architectures (such as an isolated single-page JavaScript frontend making asynchronous XMLHttpRequests to an independent backend API), modern web browsers will automatically block network data transfers cross-domain due to Same-Origin security policies.

If your routing infrastructure is not explicitly configured to emit Cross-Origin Resource Sharing (CORS) access control parameters, your client runtime calls will break, throwing the fatal browser console error: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Implementation Guide & Setup Steps

To implement this high-performance CORS handshake directly within your Nginx routing block, complete these server operations:

1. Locate Your Virtual Host Config: Connect to your server node and open your site configuration file using administrative editing privileges:

$ sudo nano /etc/nginx/sites-available/default

1. Apply the Route Block Configurations: Navigate into your active routing location block (e.g., location /api/) and inject the CORS matching parameters outlined below.

# IMPORTANT: To lock down production security constraints, replace the generic fallback values # below with your exact, verified client web application domain origin (e.g., https://yourfrontend.com).

1. Audit Your Web Server Formatting: Run the Nginx internal testing utility to ensure there are no missing terminal semi-colons or broken block parameters inside your configuration layout:

$ sudo nginx -t

1. Reload Your Live Server Daemons: Trigger a graceful configuration reload to apply your active access constraints instantly without severing active client socket connections:

$ sudo systemctl reload nginx

location /api/ { # 1. Define your strict whitelist origin domain boundaries add_header 'Access-Control-Allow-Origin' 'https://yourfrontend.com' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always; add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization' always; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;

# 2. Intercept and Handle Browser Preflight OPTIONS Handshakes Instantly if ($request_method = 'OPTIONS') { add_header 'Access-Control-Allow-Origin' 'https://yourfrontend.com'; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE'; add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization';

# Cache the results of this preflight handshake permission for 20 days (in seconds) add_header 'Access-Control-Max-Age' 1728000;

add_header 'Content-Type' 'text/plain; charset=utf-8'; add_header 'Content-Length' 0;

return 204; # Return 204 No Content back to the browser immediately } }