In Chapter 1 I claimed our entire Auth Gateway is built on top of one NGINX directive: auth_request . This chapter is a deep dive into how that directive actually works, and the four or five sharp edges that bit us before we got the config right.

If you already know auth_request cold, skim to "Sharp edge 1" near the bottom — that's where the real war stories are.

What auth_request actually does

Drop this in a location block:

location /user-management/ { auth_request /auth ; proxy_pass http://user-service ; }

Enter fullscreen mode

Exit fullscreen mode

When a request matches /user-management/ , NGINX:

Pauses the main request before doing anything to the upstream.

Fires an internal subrequest to /auth .

Looks at the subrequest's HTTP status:

2xx → continue with the main request.

401 or 403 → abort the main request and return that status to the client.

Anything else → fall through to your error_page directives, or return 500.

That's the entire surface area.…