Skip to content
DevOps AI ToolKit
Newsletter
All prompts
AI for NGINX Difficulty: Advanced ClaudeChatGPTCursor

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

More NGINX prompts & error guides

Browse every NGINX prompt and troubleshooting guide in one place.

Free download · 368-page PDF

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.