Nginx (Part 3): Internal Requests and Authentication
Requests nginx makes to itself (internal, named locations, error_page, X-Accel-Redirect), auth_request and the request phases, who really authenticates, trust boundaries, and which directive changes which of the four messages.
Nginx series: 1. How Nginx Runs · 2. Routing Requests · 3. Internal Requests & Auth · 4. Gateway Auth in Practice · Extra: Variables & Dynamic Proxy · Refresher & Quick Reference
So far every request came from a client. This part covers the requests nginx makes to itself (internal redirects and subrequests), how that machinery is used to put authentication in front of every backend, and finally which directive changes which of the four HTTP messages involved in a proxied request.
It builds directly on Part 2: server blocks, location matching and the proxy_pass path rule (9.6.1). The examples use the same two servers:
| Server | IP | Nginx package | What runs there |
|---|---|---|---|
server14 (server 14) | 10.20.30.14 | nginx.org package | Several Django apps (tool1, tool2, tool3, tool4) via uwsgi, each on its own domain |
server85 (server 85) | 10.20.30.185 | Ubuntu/Debian package | My devicehub app: React frontend + FastAPI backend, path-based routing |
📑 Table of Contents
- 14. Advanced —
internal,auth_request,location = /__whoami- 14.1 External vs internal requests
- 14.2
internal— a location clients can’t reach - 14.3 Named locations
@name— always internal - 14.4
error_page— internal redirect on an error code - 14.5
auth_request— nginx asks “is this user allowed?” before every request - 14.6
location = /__whoami— the auth endpoint - 14.7 Full working example (server 85 style)
- 14.8 Flow of one protected request
- 14.9
X-Accel-Redirect— a response header nginx understands - 14.10 Summary of internal machinery
- 15. Authentication with nginx — The Full Picture
- 15.1 Authentication vs authorization
- 15.2 Who actually checks the credentials?
- 15.3 Exactly how a request flows through
auth_request(corrected) - 15.4 Can the auth service set cookies or issue tokens?
- 15.5 Caching auth results
- 15.6 The trust boundary — the part that makes or breaks gateway auth
- 15.7 When gateway auth fits — and when it doesn’t
- 15.8 External services behind nginx
- 15.9 Pitfalls checklist
- 16. Request vs Response — Which Directive Changes Which Message
14. Advanced — internal, auth_request, location = /__whoami
First the machinery: how nginx makes requests to itself (internal redirects and subrequests), and the directives built on it: internal, @named locations, error_page, auth_request and /__whoami.
14.1 External vs internal requests
| External request | Internal request | |
|---|---|---|
| Who starts it | the browser / curl | nginx itself |
| Visible to client? | yes | no — happens inside nginx |
| Examples | GET /api/devices/ | try_files fallback to /index.html, error_page, auth_request subrequest, X-Accel-Redirect |
I’ve already used one without knowing: try_files $uri $uri/ /index.html; — the jump to /index.html is an internal redirect. The browser asked for /devices/5 and never learns nginx actually served /index.html.
14.2 internal — a location clients can’t reach
1
2
3
4
location /protected_files/ {
internal; # only internal redirects/subrequests may use this location
alias /srv/files/;
}
- Browser requests
GET /protected_files/report.pdfdirectly → 404. - nginx itself (via
auth_request,error_page,X-Accel-Redirect,try_files,rewrite) → allowed.
Think of it as a staff-only door inside the building: customers can’t open it, staff can.
14.3 Named locations @name — always internal
1
2
3
location @login {
return 302 /login?next=$request_uri;
}
A named location can’t be addressed by any URL at all; it’s only a target for try_files, error_page, etc. Example:
1
2
3
4
5
6
location / {
try_files $uri @backend; # file not found → hand off to the backend
}
location @backend {
proxy_pass http://127.0.0.1:8000;
}
14.4 error_page — internal redirect on an error code
1
2
3
error_page 404 /404.html; # show a custom page (internal redirect, client still sees 404)
error_page 401 = @login; # "=" → response code comes from @login (here: a redirect)
error_page 502 503 504 /maintenance.html;
14.5 auth_request — nginx asks “is this user allowed?” before every request
The problem: I want /api/ (or the whole site) protected by login, but I don’t want every backend/static location to implement auth itself.
The idea: before handling a request, nginx makes an internal subrequest to an auth endpoint. The auth endpoint’s status code decides:
| Subrequest returns | nginx does |
|---|---|
| 2xx (200, 204) | ✅ allow — continue with the original request |
| 401 or 403 | ❌ deny — returns that code to the client (can be caught with error_page) |
| anything else | 💥 500 Internal Server Error |
The auth endpoint’s body is ignored; only status (and optionally headers) matter.
Who really checks credentials, the exact phase-by-phase flow, cookies/tokens, shared secrets, roles, trust boundaries and when this design fits → Section 15.
14.6 location = /__whoami — the auth endpoint
1
2
3
4
5
6
7
8
location = /__whoami {
internal; # browsers can't call it directly
proxy_pass http://127.0.0.1:8000/auth/whoami; # FastAPI checks the session/token
proxy_pass_request_body off; # don't send the original body (e.g. big uploads)
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri; # tell auth which URL was requested
proxy_set_header X-Original-Method $request_method;
}
Why it’s written this way:
=→ exact match, highest priority; nothing else can shadow it, and it’s the fastest match./__whoamiwith double underscore → a naming convention so it can’t collide with a real app or React route (no one builds a page called/__whoami).internal→ clients can’t probe it; onlyauth_requestuses it.- The original request’s headers (including Cookie and Authorization) are passed to the subrequest by default — that’s how the backend sees the session.
proxy_passhere has a URI part (/auth/whoami), so the backend receives/auth/whoami, not/__whoami(trailing-URI rule, 9.6).
Exact-match locations and the path rule, step by step
This is the proxy_pass path rule (9.6.1) applied to an exact-match location: the whole path matched, so the whole path is replaced and there is no remainder. The same thing with another auth endpoint:
1
2
3
4
location = /__auth_qaview {
internal;
proxy_pass http://127.0.0.1:8000/api/auth/verify;
}
1
2
3
4
original path (the subrequest) /__auth_qaview
matched part /__auth_qaview (entire path)
remainder (nothing)
sent path /api/auth/verify + (nothing) = /api/auth/verify
The backend receives /api/auth/verify — not /api/auth/verify/__auth_qaview. The name /__auth_qaview is only an internal label inside nginx; the backend never sees it. (If the backend needs to know what the user originally asked for, pass it explicitly: proxy_set_header X-Original-URI $request_uri;.)
14.7 Full working example (server 85 style)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
server {
listen 80;
server_name 10.20.30.185;
root /home_ldap/user01/workspace/devicehub_frontend/dist;
index index.html;
# ── Public: the login page and auth API must NOT require login ──
location /api/auth/ {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
}
# ── Protected API ──
location /api/ {
auth_request /__whoami; # 1. ask first
auth_request_set $auth_user $upstream_http_x_user; # 2. capture X-User header from the auth response
proxy_set_header X-User $auth_user; # 3. pass identity to the real backend
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
# ── The internal auth check ──
location = /__whoami {
internal;
proxy_pass http://127.0.0.1:8000/api/auth/whoami;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
# ── Frontend (left public here so the login page can load) ──
location / {
try_files $uri $uri/ /index.html;
}
# ── Unauthenticated → JSON 401 for the API ──
error_page 401 = @unauthorized;
location @unauthorized {
default_type application/json;
return 401 '{"detail":"Not authenticated"}';
}
}
For a classic server-rendered site you’d instead redirect to a login page:
1
2
3
4
error_page 401 = @login;
location @login {
return 302 /login?next=$request_uri;
}
14.8 Flow of one protected request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Browser: GET /api/devices/ Cookie: session=abc
│
▼
nginx: location /api/ matched → sees auth_request /__whoami
│
├──► INTERNAL subrequest: GET /__whoami (Cookie: session=abc copied along)
│ location = /__whoami → proxy_pass → FastAPI /api/auth/whoami
│ FastAPI: session valid → 204, X-User: user01
│◄──── 204
│
│ 2xx → allowed. auth_request_set: $auth_user = "user01"
│
├──► proxy_pass → FastAPI /api/devices/ (X-User: user01)
│◄──── 200 JSON
▼
Browser receives JSON. (It never saw /__whoami.)
If the session is invalid:
/__whoami → 401 → nginx stops → error_page 401 → @unauthorized → client gets 401 JSON
/api/devices/ backend is never even called.
Every protected request costs one extra subrequest. For heavy traffic you can cache auth results (proxy_cache keyed on the cookie, 15.5) — usually unnecessary on an internal tool.
Check that the module is present (both packages normally include it):
1
nginx -V 2>&1 | grep -o with-http_auth_request_module
14.9 X-Accel-Redirect — a response header nginx understands
If a backend response contains X-Accel-Redirect: /some/uri, nginx does not pass that response to the client; it performs an internal redirect to /some/uri instead. Typical use: the backend checks permissions, then lets nginx serve a protected file from an internal location:
1
2
3
4
5
location /protected_files/ {
internal; # clients can't request it directly
alias /srv/files/;
}
# backend answers with the header: X-Accel-Redirect: /protected_files/report.pdf
14.10 Summary of internal machinery
| Feature | Starts an internal request when… | Typical use |
|---|---|---|
try_files ... /index.html | file not found | SPA routing |
error_page CODE target | a response has that code | custom error pages, login redirect |
auth_request /x | before every request in that location | central authentication |
X-Accel-Redirect header | backend sends that header | protected downloads |
internal; | — (marks a location as internal-only) | hide auth endpoints/files |
@name | — (always internal) | fallback handlers |
15. Authentication with nginx — The Full Picture
Section 14 showed the mechanics of auth_request. This section answers the questions that come right after: who really authenticates, how a request flows through it exactly, what happens to cookies and tokens, whether backends need shared secrets/DBs, and when this design is right or wrong.
15.1 Authentication vs authorization
| Question | Where it can live | |
|---|---|---|
| Authentication | “Who are you? Is your session/token/login valid?” | gateway (nginx + auth service) or app |
| Authorization | “May this user do this action on this object?” (e.g. delete test session 42) | the app — it’s business logic |
When an architecture diagram puts “Authentication” on the API Gateway / Load Balancer box (next to SSL termination, routing, rate limiting, load balancing), it means the first row: reject requests without valid credentials before they reach any backend. It’s the standard API-gateway feature list (nginx, F5, Kong, AWS API Gateway, Envoy all advertise it). It does not mean the gateway decides app permissions.
15.2 Who actually checks the credentials?
With
auth_request, nginx does NOT authenticate. It only enforces the verdict. The auth service (Flask, FastAPI, anything — e.g. on port 9000) checks the cookie or token against LDAP or the DB and answers 2xx, 401, or 403. Nginx just obeys the answer.
The exceptions — where nginx itself checks credentials:
| Method | Who checks | Typical use |
|---|---|---|
auth_request | an external auth service; nginx obeys its status | SSO, LDAP, sessions, JWT via a service |
auth_basic | nginx, against a password file | quick protection for internal tools |
mTLS (ssl_verify_client) | nginx, during TLS: client must present a cert signed by your CA | machine-to-machine, high security |
auth_jwt | nginx, validates JWT signature/expiry — NGINX Plus only (commercial) | API gateways on NGINX Plus |
allow / deny | nginx, by client IP — access control, not identity | “only the office network” |
auth_basic — browser shows a username/password popup:
1
2
sudo apt install apache2-utils # provides htpasswd
sudo htpasswd -c /etc/nginx/.htpasswd user01 # -c creates the file; omit -c to add more users
1
2
3
4
5
6
7
location /admin/ {
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-User $remote_user; # nginx knows the username after basic auth
}
Only safe over HTTPS — basic auth sends the password base64-encoded, i.e. readable, on every request.
mTLS — the client proves identity with a certificate:
1
2
3
4
5
6
7
8
9
10
11
12
server {
listen 443 ssl;
ssl_certificate /etc/nginx/ssl/server.crt;
ssl_certificate_key /etc/nginx/ssl/server.key;
ssl_client_certificate /etc/nginx/ssl/company-ca.crt; # CA that signed the allowed client certs
ssl_verify_client on; # no valid client cert → 400, never reaches a location
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header X-Client-DN $ssl_client_s_dn; # e.g. "CN=ci-runner-01,O=Company"
}
}
auth_jwt (NGINX Plus only — open-source nginx does JWT checks via auth_request to a small service):
1
2
3
4
5
6
location /api/ {
auth_jwt "api";
auth_jwt_key_file /etc/nginx/jwks.json; # public keys to verify signatures
proxy_set_header X-User $jwt_claim_sub; # claims become variables
proxy_pass http://127.0.0.1:8000;
}
IP rules combined with a password — satisfy any:
1
2
3
4
5
6
7
8
location /internal/ {
satisfy any; # pass if EITHER check passes (default is "all")
allow 10.20.0.0/16; # office network: no password needed
deny all;
auth_basic "Restricted"; # everyone else: password
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://127.0.0.1:8000;
}
15.3 Exactly how a request flows through auth_request (corrected)
My first mental model, checked line by line:
| What I thought | Reality |
|---|---|
| nginx checks the Host matches, then the path matches (exact or partial), then goes inside that block | ✅ Correct — first listen IP:port, then server_name, then the best location (9.2) |
“if the first line is auth_request…” | ❌ Line order inside a location does not matter. The config is declarative; nginx processes every request in fixed phases. auth_request belongs to the access phase, proxy_pass to the content phase, so auth always runs first wherever it’s written. It can even be written once at server {} level and inherited. |
the auth URL is defined in a location in another server block, and since it’s internal the host doesn’t matter | ❌ The subrequest is resolved inside the SAME server block. internal means “clients can’t call it”, not “global”. Every server block that uses auth_request /__auth needs its own location = /__auth — write it once in a snippet and include it (example below). What can live anywhere is the auth service that location proxies to. |
| the auth location proxies to the auth server, the response comes back, nginx captures it into variables we define | ✅ Correct — auth_request_set $var $upstream_http_<header>; The status code decides allow/deny. |
then it returns to the same place and “hits the next line”, i.e. the proxy_pass | ⚠️ Conceptually yes — control returns to the original request, which moves on through its remaining phases (POST_ACCESS, PRECONTENT) to CONTENT, where proxy_pass runs. Not “next line”. |
| it forwards the entire request with the same payload and modified headers | ✅ Correct — body untouched (it was never sent to the auth service), original headers plus whatever proxy_set_header adds or overrides |
The phases, in the order nginx runs them for every request. Part 2 introduced a simplified version; here are all 11 (names as in the nginx development guide). Phases marked (internal) have nothing to configure:
1
2
3
4
5
6
7
8
9
10
11
12
13
# Phase What runs there
1 POST_READ realip (take the real client IP from a trusted proxy header)
2 SERVER_REWRITE rewrite / return / set / if written at server level
3 FIND_CONFIG choose the location (9.2 rules)
4 REWRITE rewrite / return / set / if written inside the location
5 POST_REWRITE (internal) re-run location search if the URI was rewritten
6 PREACCESS limit_req, limit_conn (rate / connection limiting)
7 ACCESS allow/deny, auth_basic, auth_request, auth_jwt
8 POST_ACCESS (internal) applies "satisfy all | any" to the access results
9 PRECONTENT try_files, mirror
10 CONTENT proxy_pass, uwsgi_pass, fastcgi_pass, static files (root/alias, index)
11 LOG access_log
+ response filters on the way out: add_header, gzip, sub_filter, ...
Where proxy_pass runs — an auth set has two of them:
proxy_passin the protected location (to the backend) runs in phase 10 CONTENT of the main request.proxy_passdoesn’t execute “at its line”; it installs the location’s content handler, which is why it always runs last no matter where it’s written.proxy_passinlocation = /__auth(to the auth service) runs in phase 10 CONTENT of the subrequest. That subrequest is launched from phase 7 ACCESS of the main request, and the main request waits in ACCESS until the answer arrives. (Subrequests skip the ACCESS phase themselves, so/__authis never auth-checked.)
1
2
3
4
5
6
7
8
9
10
MAIN REQUEST GET /api/devices
2 SERVER_REWRITE → 3 FIND_CONFIG (location /api/) → 4 REWRITE → 6 PREACCESS
→ 7 ACCESS: auth_request /__auth ───────────────┐ main request waits here
▼
SUBREQUEST /__auth (same server block)
FIND_CONFIG (location = /__auth) → ... → 10 CONTENT: proxy_pass → auth service
│ answer: 2xx / 401 / 403
◄─────────────────────────────────────────────┘
2xx → continue 401/403 → stop, send that code to the client
→ 8 POST_ACCESS → 9 PRECONTENT → 10 CONTENT: proxy_pass → backend → 11 LOG
⚠️ Pitfall that follows from the phases — return runs BEFORE auth:
1
2
3
4
location /admin/ {
auth_request /__auth;
return 200 "secret stuff"; # served to EVERYONE: return is phase 4 REWRITE, auth is phase 7 ACCESS
}
The same fact is useful for CORS: if ($request_method = OPTIONS) { return 204; } answers preflights before auth — correct, since preflights never carry credentials.
The refined flow, step by step:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Request: GET /sessions/42 Host: gw.example.com Cookie: session=abc
① Server selection listen 443 + server_name gw.example.com → server block "gw"
② Location selection longest prefix /sessions/ → location /sessions/
③ Rewrite phase no return/rewrite here → continue
④ Access phase auth_request /__auth
├─ nginx creates an INTERNAL SUBREQUEST to /__auth
│ resolved in the SAME server block → location = /__auth { internal; ... }
│ it carries the original headers (Cookie, Authorization) but no body
├─ that location proxy_passes to the auth service (http://10.7.2.50:9000/verify)
├─ auth service checks session=abc against LDAP/DB
│ → 204 X-User: user01 X-Roles: qa,admin
├─ nginx reads the STATUS: 2xx → allowed (401/403 → stop & deny; other → 500)
└─ auth_request_set copies X-User / X-Roles into $user / $roles
⑤ Content phase proxy_pass http://compute2:8001
└─ new request to the backend: same method, path, body, client headers
+ proxy_set_header X-User $user, X-Roles $roles
⑥ Response backend 200 JSON → nginx → browser
(the browser never sees /__auth or the auth service)
The complete config for that flow, shared across several server blocks:
1
2
3
4
5
6
7
8
9
# /etc/nginx/snippets/auth.conf — written once
location = /__auth {
internal;
proxy_pass http://10.7.2.50:9000/verify; # auth service, can be on another host
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri; # auth service otherwise only sees "/verify"
proxy_set_header X-Original-Method $request_method;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
server {
listen 443 ssl;
server_name gw.example.com;
# ssl_certificate ... ;
include snippets/auth.conf; # pasted here → location = /__auth exists in THIS block
location /sessions/ {
auth_request /__auth;
auth_request_set $user $upstream_http_x_user;
auth_request_set $roles $upstream_http_x_roles;
proxy_set_header Host $host;
proxy_set_header X-User $user;
proxy_set_header X-Roles $roles;
proxy_pass http://compute2:8001;
}
location /tools/ {
auth_request /__auth;
auth_request_set $user $upstream_http_x_user;
auth_request_set $roles $upstream_http_x_roles;
proxy_set_header Host $host;
proxy_set_header X-User $user;
proxy_set_header X-Roles $roles;
proxy_pass http://compute2:8002;
}
}
server {
listen 443 ssl;
server_name ai.example.com;
include snippets/auth.conf; # needed AGAIN — different server block
location / {
auth_request /__auth;
auth_request_set $user $upstream_http_x_user;
proxy_set_header Host $host;
proxy_set_header X-User $user;
proxy_pass http://ai-backend:8000;
}
}
It runs on every request. nginx keeps no memory between requests: every request to a protected location triggers its own auth subrequest (unless you add caching, 15.5).
15.4 Can the auth service set cookies or issue tokens?
Not by itself: the auth subrequest’s body is discarded and its headers never reach the browser. So if /verify returns a refreshed session cookie, the browser never gets it — unless you forward it by hand (messages shown in Section 16):
1
2
3
4
5
6
location /api/ {
auth_request /__auth;
auth_request_set $new_cookie $upstream_http_set_cookie; # capture from the AUTH response
add_header Set-Cookie $new_cookie always; # put it on the response to the BROWSER
proxy_pass http://127.0.0.1:8000;
}
Forward one cookie only (several Set-Cookie headers through one variable is unreliable), and remember add_header inheritance (9.9). Login, refresh and logout don’t need this trick — make them ordinary public locations so their Set-Cookie reaches the browser normally:
1
2
3
4
location /auth/ { # login / refresh / logout — public, NOT behind auth_request
proxy_pass http://127.0.0.1:9000;
proxy_set_header Host $host;
}
15.5 Caching auth results
Every protected request costs one auth subrequest — usually a fast local call. If it matters, nginx can cache the verdict per credential:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# in http {}
proxy_cache_path /var/cache/nginx/auth levels=1 keys_zone=authcache:10m max_size=50m inactive=10m;
location = /__auth {
internal;
proxy_pass http://127.0.0.1:9000/auth/verify;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_cache authcache;
proxy_cache_key "$http_authorization$cookie_session"; # one cache entry per credential
proxy_cache_valid 200 204 30s; # remember "allowed" for 30s
proxy_ignore_headers Cache-Control Expires; # cache even if the auth service says no-cache
}
Trade-off: a cached “allowed” can outlive a logout by up to 30 s. Responses carrying
Set-Cookiearen’t cached by default.
15.6 The trust boundary — the part that makes or breaks gateway auth
Backends trust X-User blindly. That is only safe if nothing except nginx can reach them.
⚠️ Pitfall 1 — bypassing nginx: if 10.7.2.48:8001 is reachable from the network, anyone can call it directly with X-User: admin. Ways to close it (pick at least one):
| Option | How |
|---|---|
| Same machine, loopback | backend binds 127.0.0.1 (or Docker -p 127.0.0.1:8001:8000) — simplest |
| Private network + firewall | backends on another host, firewall allows only the gateway’s IP |
| Docker internal network | backends have no published ports; nginx container on the same network |
| Shared secret header | nginx adds proxy_set_header X-Gateway-Token "<long random>";, backend rejects requests without it |
| mTLS gateway → backend | proxy_ssl_certificate on nginx; backend requires that client cert |
So backends do not have to be on the same machine — they have to be unreachable except via the gateway. Loopback is just the easiest way to guarantee that.
⚠️ Pitfall 2 — client-supplied identity headers: a client can send X-User: admin to nginx.
- In a protected location,
proxy_set_header X-User $user;replaces whatever the client sent — safe. - In a location without
auth_requestthat proxies to the same backend, the client’s header passes straight through! Blank it explicitly:
1
2
3
4
5
location /public/ {
proxy_set_header X-User ""; # empty value = header not sent upstream
proxy_set_header X-Roles "";
proxy_pass http://127.0.0.1:8001;
}
The backend can additionally reject requests that lack the gateway secret header (code in Part 4, 18.3).
⚠️ Pitfall 3 — return in a protected location skips auth (15.3).
15.7 When gateway auth fits — and when it doesn’t
Gateway auth answers one question centrally — “is this a valid, logged-in user?” — for many services sharing one user base. It is not a replacement for an application’s own login.
| Situation | Authentication lives in |
|---|---|
| Many internal services, same users | gateway / central identity provider; each app keeps its own permissions |
| One self-contained product (UI + backend) | the app; nginx only does TLS and routing |
| A product deployed for many customers | the app, optionally with a “trust the proxy’s user header” mode for customers who run an SSO gateway |
| External systems calling your API | standard API keys / OAuth tokens checked by the app — never gateway headers |
Both styles can sit behind the same nginx:
1
2
3
4
5
6
7
8
9
10
11
12
13
# Internal tools: nginx does the coarse check, the app decides permissions
location /tools/ {
auth_request /__auth; # "is this a logged-in user?"
auth_request_set $user $upstream_http_x_user;
proxy_set_header X-User $user;
proxy_pass http://tools-backend:8000;
}
# Self-contained product: nginx only routes, the app runs its own login
location /product/ {
proxy_pass http://product-backend:8000;
proxy_set_header Host $host;
}
Defense in depth is common: the gateway rejects unauthenticated traffic early, and the app still validates and authorizes. Design discussion (BFF, multi-customer products, proxy-auth modes) is in Part 4, 17.
15.8 External services behind nginx
The rule: nginx can only modify requests whose URL points at nginx. If the browser calls
https://partner.example.com/...directly (afetchor an<iframe src>), your nginx never sees it and can’t add credentials. To add credentials, route the call through your nginx.
Inject the partner’s credential at the gateway — the browser never sees the key:
1
2
3
4
5
6
7
8
9
location /partner/ {
auth_request /__auth; # caller must be logged in with us
proxy_pass https://partner.example.com/; # path "/" strips /partner/ (9.6.1)
proxy_set_header Host partner.example.com; # the partner's name, not $host (9.9)
proxy_ssl_server_name on; # send SNI to the partner's HTTPS server
proxy_set_header Authorization "Bearer <partner-api-key>";
proxy_set_header Cookie ""; # don't leak our session cookie
proxy_set_header X-User "";
}
GET /partner/v1/items → the partner receives GET /v1/items with the key. It’s one browser request; the auth subrequest and the forward both happen inside it (15.3). To pick the key per user or role, let the auth service return it in a header and inject that instead:
1
2
auth_request_set $ext_token $upstream_http_x_ext_token;
proxy_set_header Authorization "Bearer $ext_token";
Limits: the partner sees every call as one service account, the secret lives in nginx config (or the auth service), and there’s no reshaping or error handling. When you need logic, call the partner from your backend instead: browser → nginx → your backend → partner.
Iframes: an iframe pointing at the partner’s domain loads directly from them, so their app must handle login (SSO or an embed token). To run it through our nginx, give it its own subdomain rather than a sub-path, because absolute asset paths break under a prefix (9.6.1):
1
2
3
4
5
6
7
8
9
10
11
server {
listen 443 ssl;
server_name partner.ourapp.example.com;
include snippets/auth.conf; # location = /__auth must exist in this block
location / {
auth_request /__auth;
proxy_pass http://10.0.0.20:8000; # no path: identical paths on both sides
proxy_set_header Host 10.0.0.20;
proxy_set_header X-API-Key "<partner-key>";
}
}
Keep gateway headers internal:
X-User/X-Rolesare a contract inside your own deployment. Partners calling your API get standard API keys or OAuth tokens.
Step-by-step implementation (the backend integration layer, a verify endpoint that hands out per-service keys, embed tokens, SSO, choosing between them) is in Part 4, 20.
15.9 Pitfalls checklist
| ✔ | Check |
|---|---|
| ☐ | Backends unreachable except through nginx (loopback / firewall / internal network / gateway secret / mTLS) |
| ☐ | Identity headers blanked (proxy_set_header X-User "";) in every non-protected location that proxies to those backends |
| ☐ | No return inside protected locations (it runs before auth) |
| ☐ | location = /__auth exists (via include) in every server block that uses auth_request |
| ☐ | /auth/login, /auth/refresh, /auth/logout are public, normal locations — not behind auth_request |
| ☐ | Auth endpoint returns only 2xx / 401 / 403 (anything else = 500 for the user) |
| ☐ | Set-Cookie from the auth subrequest is forwarded only if intended (auth_request_set + add_header ... always) |
| ☐ | Locations re-declare all needed proxy_set_header / add_header (inheritance is all-or-nothing) |
| ☐ | Session cookies HttpOnly; Secure only works over HTTPS; Domain= set if subdomains must share the login |
| ☐ | Cross-origin + cookies → specific origin + Access-Control-Allow-Credentials: true (never *) |
| ☐ | Authorization (who may do what) stays in each app |
| ☐ | Externals use standard credentials; gateway headers stay internal |
16. Request vs Response — Which Directive Changes Which Message
A proxied request is not one message but four, and each has its own headers. Almost every header question (“does the backend see this?”, “does the browser get this?”) is answered by asking which of the four messages a directive touches.
16.1 The four messages and nginx’s defaults
1
2
3
4
① request ② request (a NEW one)
Browser ───────────────► nginx ───────────────► Backend
◄─────────────── ◄───────────────
④ response ③ response
| Message | What nginx does by default |
|---|---|
| ① browser → nginx | reads it; headers available as variables ($http_*, $cookie_*) |
| ② nginx → backend | builds a new request: client headers copied, except Host (set to $proxy_host) and Connection (set to close) — see 9.9 |
| ③ backend → nginx | reads it; headers available as $upstream_http_* |
| ④ nginx → browser | backend headers copied, except Date, Server, X-Pad and X-Accel-*, which nginx does not pass on |
With auth_request there are two extra messages — the internal subrequest to the auth service and its response. Their headers go nowhere unless you capture them (16.5).
16.2 Cookie vs Set-Cookie
| Header | Travels in | Direction | Meaning |
|---|---|---|---|
Cookie: session=abc | a request (① → ②) | browser → server | “here is the cookie I already have” |
Set-Cookie: session=new | a response (③ → ④) | server → browser | “please store this cookie” |
- Both pass through nginx automatically: the browser’s
Cookieis copied into ②, a backend’sSet-Cookieis copied into ④. - Only browsers store cookies, so
Set-Cookieonly makes sense on a response going to the browser. - Cookies are scoped by domain + path, not port;
Domain=.example.comshares one across subdomains;Securecookies are only stored over HTTPS (so not on plain-http server 85). - The browser only ever sees ① and ④. A cookie set “by the auth service” or “by the backend” is, to the browser, simply a cookie from the host in the URL bar.
16.3 Which directive changes which message
| Message | Directive | Effect |
|---|---|---|
| ② to backend | proxy_set_header Name value; | add or override a header; an empty value removes it |
| ② | proxy_pass_request_headers off; | send none of the client’s headers |
| ② | proxy_pass_request_body off; | send no body (typical for auth subrequests) |
| ④ to browser | add_header Name value [always]; | add a header — only on 2xx/3xx responses unless always |
| ④ | proxy_hide_header Name; | drop a header the backend sent |
| ④ | proxy_pass_header Name; | let through a header nginx normally drops (e.g. Server) |
| ④ | proxy_cookie_path / proxy_cookie_domain / proxy_cookie_flags | rewrite attributes of the backend’s Set-Cookie (16.6) |
| ④ | proxy_redirect | rewrite the backend’s Location header |
| ④ | expires | add Expires / Cache-Control |
| (none) | auth_request_set $var $upstream_http_name; | copy a header of the auth response into a variable, to use in ② or ④ |
⚠️
proxy_set_headerandadd_headerinherit into a location only if it defines none of its own (9.9).
16.4 Reading headers as variables
| Variable | Reads | Example |
|---|---|---|
$http_<name> | a header of the client request ① | $http_authorization, $http_user_agent |
$cookie_<name> | one cookie from ① | $cookie_session |
$upstream_http_<name> | a header of the backend / auth response ③ | $upstream_http_x_user |
$sent_http_<name> | a header of the response sent to the client ④ | $sent_http_content_type |
Header names become lowercase with - turned into _: X-User → x_user, Set-Cookie → set_cookie. (Query parameters work the same way, $arg_<name>; variables in general: Extra.)
16.5 Worked example — a refreshed cookie through auth_request
Message numbers here count every hop, including the auth subrequest (② ③), so the backend messages are ④ ⑤ and the browser response is ⑥.
1
2
3
4
5
6
7
8
9
10
11
12
13
location /api/ {
auth_request /__auth;
auth_request_set $auth_cookie $upstream_http_set_cookie; # capture Set-Cookie from the AUTH response
add_header Set-Cookie $auth_cookie always; # attach it to the response going to the BROWSER
proxy_pass http://127.0.0.1:8001;
}
location = /__auth {
internal;
proxy_pass http://10.12.3.4/something/auth;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Browser nginx Auth (/__auth) Backend (8001)
│ ① REQUEST │ │ │
│ GET /api/devices │ │ │
│ Cookie: session=old │ │ │
│────────────────────────►│ ② REQUEST (internal) │ │
│ │ Cookie: session=old │ │
│ │───────────────────────────►│ │
│ │ ③ RESPONSE 204 │ │
│ │ Set-Cookie: session=new │ │
│ │◄───────────────────────────│ │
│ │ auth_request_set → $auth_cookie = "session=new" │
│ │ │
│ │ ④ REQUEST GET /api/devices │
│ │ Cookie: session=old (NO Set-Cookie here) │
│ │───────────────────────────────────────────────────►│
│ │ ⑤ RESPONSE 200 JSON (knows nothing of new cookie)│
│ │◄───────────────────────────────────────────────────│
│ ⑥ RESPONSE 200 JSON │ │
│ Set-Cookie: session=new │ ← added by add_header from $auth_cookie │
│◄────────────────────────│ │
browser stores session=new; the next request sends Cookie: session=new
- The backend never sees the new cookie: ④ carries only the browser’s
Cookie, and ⑤ doesn’t contain it. - nginx carries it in
$auth_cookiefor this one request;add_headerattaches it to ⑥. Withoutadd_headerit is dropped; if the auth service sends none, nothing is added. /__authruns on every request. On 401 the backend is never called and the browser gets the 401 (the UI then sends the user to login).
16.6 Rewriting a backend’s cookies
When an app is proxied under a different path or name, the cookies it sets may be scoped wrong for the browser. nginx can fix the Set-Cookie attributes on the way out (④):
1
2
3
4
5
6
location /app/ {
proxy_pass http://10.0.0.20:8000/; # the app thinks it lives at /
proxy_cookie_path / /app/; # its "Path=/..." cookies become "Path=/app/..."
proxy_cookie_domain 10.0.0.20 $host; # "Domain=10.0.0.20" → the name the browser used
proxy_cookie_flags ~ httponly samesite=lax; # add flags to all its cookies (nginx ≥ 1.19.3)
}