NGINX JWT / OAuth2 Token Validation Prompt
Validate JWT / OAuth2 access tokens at the NGINX edge before requests reach your backend — signature, expiry, issuer, audience, and scope checks — using auth_jwt (Plus) or an auth_request bridge to an introspection service on open-source NGINX.
- Target user
- Engineers terminating API auth at the NGINX reverse proxy
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior API-gateway engineer who terminates OAuth2/JWT validation at NGINX so backends can trust the request. You know exactly what NGINX Plus `auth_jwt` gives you versus what you must build on open-source NGINX. I will provide: - Whether I run NGINX Plus or open-source (paste `nginx -V`): [PASTE] - My identity provider and how to reach its JWKS / introspection endpoint: [DESCRIBE + URL] - The token format (JWT vs opaque) and where it arrives (Authorization: Bearer, cookie): [DESCRIBE] - The claims I must enforce (`iss`, `aud`, `exp`, required `scope`/roles): [LIST] - The upstream that should receive validated requests: [PASTE] Design the validation: 1. **Pick the mechanism** — if NGINX Plus, use `auth_jwt` + `auth_jwt_key_request` (or `auth_jwt_key_file`) against the JWKS. If open-source, use `auth_request` to an internal introspection/validation endpoint (or an `njs` module), and explain the tradeoff clearly. 2. **Signature + JWKS** — configure key retrieval/caching so rotated signing keys are picked up without a reload; note the cache TTL. 3. **Claim enforcement** — reject on missing/expired `exp`, wrong `iss`, wrong `aud`, and insufficient `scope`/roles. Show how to map a failed claim to a `401` vs `403`. 4. **Pass identity downstream** — forward validated claims to the upstream as trusted headers (`proxy_set_header X-User ...`) and, critically, STRIP any client-supplied copies of those headers so callers can't spoof identity. 5. **Error responses** — return clean `401`/`403` with a `WWW-Authenticate` header, and make sure `auth_request` internal locations aren't reachable from outside. Output: (a) the full config for MY build (Plus or OSS), commented; (b) the header-stripping lines that prevent identity spoofing; (c) `curl` commands testing a valid token, an expired token, and a wrong-audience token, with expected status codes; (d) `nginx -t` verification. Apply only after `nginx -t` passes and reload.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Why this prompt works
The number-one failure here is shipping an auth_jwt config to an open-source NGINX build, where the directive doesn’t exist and — depending on how it’s wrapped — auth can end up effectively disabled. By forcing you to paste nginx -V, the prompt routes you to the right mechanism: native auth_jwt on Plus, or an auth_request/njs bridge to an introspection endpoint on OSS.
The second failure is treating a valid signature as authorization. A correctly signed token issued for a different audience is still cryptographically valid — so the prompt makes iss, aud, exp, and scope enforcement non-negotiable, and separates 401 (no/invalid token) from 403 (valid token, insufficient scope).
Passing claims downstream is where identity spoofing sneaks in: if NGINX sets X-User but doesn’t strip a client-supplied X-User, callers forge identity. The prompt bakes in the header-stripping step and a three-token curl test (valid / expired / wrong-audience) so you prove enforcement before trusting it.
Related prompts
-
NGINX Canary & Blue-Green Routing Prompt
Design percentage-based canary and blue-green traffic routing in NGINX using split_clients and upstream weighting — with a sticky cohort, an instant rollback path, and a way to force yourself onto the canary for testing.
-
NGINX CORS & Preflight Proxy Prompt
Get correct, secure CORS handling in NGINX for a reverse-proxied API — OPTIONS preflight, Access-Control-* headers, credentials, and per-origin allow-listing — without the classic duplicate-header and wildcard-with-credentials footguns.
-
NGINX Custom Error Pages & Fallback Prompt
Design clean custom error pages and graceful fallbacks in NGINX — branded 404/50x pages, an upstream-down maintenance page, and error interception that doesn't leak backend errors or break API JSON responses.
-
NGINX GeoIP2 Country Access Control Prompt
Add country- or ASN-based access control and routing to NGINX with the ngx_http_geoip2 module — allow/deny by country, route regional traffic, and set headers — while correctly resolving the real client IP behind a CDN or load balancer.
More NGINX prompts & error guides
Browse every NGINX prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.