Directiva add_header în Nginx: sintaxă și exemple de configurare

Ce face `add_header`

Directiva add_header adaugă un antet HTTP în răspunsul pe care Nginx îl trimite către browser. Este folosită în primul rând pentru antetele de securitate (Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Content-Security-Policy) și pentru antetele CORS (Access-Control-Allow-Origin).

Există două reguli de comportament pe care trebuie să le știi: în primul rând, fără parametrul always, Nginx adaugă antetul doar la răspunsurile „de succes” (200, 201, 204, 206, 301, 302, 303, 304, 307, 308), nu și la paginile de eroare 4xx/5xx; pentru antetele de securitate și CORS pune aproape întotdeauna always.

În al doilea rând, ca și la proxy_set_header, moștenirea este pe principiul „totul sau nimic”: dacă ai cinci directive add_header în server și adaugi chiar și un singur add_header într-un bloc location, cele cinci din server dispar pentru acel location!

Opțiuni și argumente

Opțiune / Parametru	Descriere
`Context: http, server, location, if în location`	Se pune de regulă în `server` sau într-un snippet inclus unde este nevoie.
`nume valoare`	Numele și valoarea antetului; dacă valoarea conține spații sau punct și virgulă, pune-o între ghilimele.
`always`	Adaugă antetul indiferent de codul de răspuns HTTP (inclusiv la 401, 403, 404, 500).
`server_tokens off`	Directivă conexă: ascunde versiunea exactă de Nginx din antetul `Server: nginx` și din paginile de eroare.

Exemple

Exemplul 1: Set recomandat de antete de securitate

Salvează-le în /etc/nginx/snippets/security-headers.conf ca să le poți reinclude și în blocurile location care au propriul add_header:

# /etc/nginx/snippets/security-headers.conf
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
add_header X-Content-Type-Options    "nosniff" always;
add_header X-Frame-Options           "SAMEORIGIN" always;
add_header Referrer-Policy           "strict-origin-when-cross-origin" always;
add_header Permissions-Policy        "geolocation=(), microphone=(), camera=()" always;

Exemplul 2: Evitarea pierderii antetelor din server într-un location

Când un location adaugă un antet nou, reinclude snippet-ul comun în acel bloc:

server {
    listen 443 ssl;
    server_name example.com;
    include snippets/security-headers.conf;

    location /static/ {
        include snippets/security-headers.conf;
        add_header Cache-Control "public, max-age=31536000, immutable";
    }
}

Exemplul 3: Antete CORS pentru fonturi sau API

Cu always, antetul CORS este prezent și când API-ul returnează 400 sau 401:

location ~* \.(woff2?|ttf|otf|eot)$ {
    add_header Access-Control-Allow-Origin "*" always;
    expires 1y;
}

Greșeli frecvente

Capcana nr. 1 în Nginx: adăugarea unui add_header Cache-Control ... într-un location șterge silențios toate antetele Strict-Transport-Security, X-Frame-Options etc. definite în server.
Activarea includeSubDomains; preload în Strict-Transport-Security înainte ca absolut toate subdomeniile să aibă HTTPS funcțional: browserele vor refuza să deschidă orice subdomeniu rămas pe HTTP.

Comenzi înrudite

ssl_certificate și HTTPS: Configurează certificatul, cheia privată, versiunile TLS (1.2/1.3) și cache-ul de sesiuni pentru HTTPS.
expires: Setează antetele Cache-Control și Expires pentru ca browserul și CDN-ul să păstreze în cache fișierele statice.
proxy_set_header: Setează sau modifică antetele HTTP trimise către backend (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto).

Ce face add_header