Post

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 (Part 3): Internal Requests and Authentication

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:

ServerIPNginx packageWhat runs there
server14 (server 14)10.20.30.14nginx.org packageSeveral Django apps (tool1, tool2, tool3, tool4) via uwsgi, each on its own domain
server85 (server 85)10.20.30.185Ubuntu/Debian packageMy devicehub app: React frontend + FastAPI backend, path-based routing
📑 Table of Contents

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 requestInternal request
Who starts itthe browser / curlnginx itself
Visible to client?yesno — happens inside nginx
ExamplesGET /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.pdf directly → 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 returnsnginx 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.
  • /__whoami with 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; only auth_request uses 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_pass here 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

FeatureStarts an internal request when…Typical use
try_files ... /index.htmlfile not foundSPA routing
error_page CODE targeta response has that codecustom error pages, login redirect
auth_request /xbefore every request in that locationcentral authentication
X-Accel-Redirect headerbackend sends that headerprotected 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

 QuestionWhere 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:

MethodWho checksTypical use
auth_requestan external auth service; nginx obeys its statusSSO, LDAP, sessions, JWT via a service
auth_basicnginx, against a password filequick protection for internal tools
mTLS (ssl_verify_client)nginx, during TLS: client must present a cert signed by your CAmachine-to-machine, high security
auth_jwtnginx, validates JWT signature/expiry — NGINX Plus only (commercial)API gateways on NGINX Plus
allow / denynginx, 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 thoughtReality
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_pass in the protected location (to the backend) runs in phase 10 CONTENT of the main request. proxy_pass doesn’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_pass in location = /__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 /__auth is 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-Cookie aren’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):

OptionHow
Same machine, loopbackbackend binds 127.0.0.1 (or Docker -p 127.0.0.1:8001:8000) — simplest
Private network + firewallbackends on another host, firewall allows only the gateway’s IP
Docker internal networkbackends have no published ports; nginx container on the same network
Shared secret headernginx adds proxy_set_header X-Gateway-Token "<long random>";, backend rejects requests without it
mTLS gateway → backendproxy_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_request that 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.

SituationAuthentication lives in
Many internal services, same usersgateway / 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 customersthe app, optionally with a “trust the proxy’s user header” mode for customers who run an SSO gateway
External systems calling your APIstandard 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 (a fetch or 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-Roles are 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
MessageWhat nginx does by default
① browser → nginxreads it; headers available as variables ($http_*, $cookie_*)
② nginx → backendbuilds a new request: client headers copied, except Host (set to $proxy_host) and Connection (set to close) — see 9.9
③ backend → nginxreads it; headers available as $upstream_http_*
④ nginx → browserbackend 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

HeaderTravels inDirectionMeaning
Cookie: session=abca request (① → ②)browser → server“here is the cookie I already have”
Set-Cookie: session=newa response (③ → ④)server → browser“please store this cookie”
  • Both pass through nginx automatically: the browser’s Cookie is copied into ②, a backend’s Set-Cookie is copied into ④.
  • Only browsers store cookies, so Set-Cookie only makes sense on a response going to the browser.
  • Cookies are scoped by domain + path, not port; Domain=.example.com shares one across subdomains; Secure cookies 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

MessageDirectiveEffect
② to backendproxy_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 browseradd_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_flagsrewrite attributes of the backend’s Set-Cookie (16.6)
④proxy_redirectrewrite the backend’s Location header
④expiresadd 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_header and add_header inherit into a location only if it defines none of its own (9.9).

16.4 Reading headers as variables

VariableReadsExample
$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_cookie for this one request; add_header attaches it to ⑥. Without add_header it is dropped; if the auth service sends none, nothing is added.
  • /__auth runs 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)
}
This post is licensed under CC BY 4.0 by the author.