From 2427245a18eaf580edaedf33c918c80b684185fb Mon Sep 17 00:00:00 2001 From: Mateen Anjum Date: Thu, 9 Jul 2026 15:59:09 -0400 Subject: [PATCH] docs: fix invalid nginx error_page 401 example for API routes The API route example used `error_page 401 =401;`, but nginx parses the `=401` as the error_page URI, so an unauthenticated API call is internally redirected to a location named /=401 instead of returning 401 to the client. Drop the directive: without an error_page for 401, nginx returns the 401 from auth_request to the client unchanged. Also add a note that the browser and API snippets show only the routing difference and the rest of the auth_request config (the auth_request_set / proxy_set_header lines that pass X-User, X-Email, token and cookies) must be replicated from the main example. Fixes #3467. Signed-off-by: Mateen Anjum --- CHANGELOG.md | 1 + docs/docs/configuration/integrations/nginx.md | 7 ++++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 788e82c2..e2bff4b2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ ## Breaking Changes ## Changes since v7.15.3 +- [#3469](https://github.com/oauth2-proxy/oauth2-proxy/pull/3469) docs: fix invalid `error_page 401 =401` in the nginx API route example and note that the shared `auth_request` config must be replicated # V7.15.3 diff --git a/docs/docs/configuration/integrations/nginx.md b/docs/docs/configuration/integrations/nginx.md index ca6402a9..ebffde4d 100644 --- a/docs/docs/configuration/integrations/nginx.md +++ b/docs/docs/configuration/integrations/nginx.md @@ -119,6 +119,10 @@ The named location pattern above ensures the browser receives a standard **302 r Redirecting authentication failures (302 to `/oauth2/sign_in`) should **only be used for browser-facing routes**. API or machine clients should receive a plain 401/403 response without redirect. ::: +:::note +The two snippets below show only the routing difference (redirect vs. no redirect). Replicate the rest of the `auth_request` configuration from the [main `location /` example](#configuring-for-use-with-the-nginx-auth_request-directive) above (the `auth_request_set`/`proxy_set_header` lines that pass `X-User`, `X-Email`, the access token and cookies to the backend); copying only the lines shown here omits those headers. +::: + #### Browser-facing routes (HTML, UI) For interactive browser routes where users should be redirected to sign in: @@ -142,7 +146,8 @@ For API endpoints where clients expect a 401/403 status code (not a redirect): ```nginx location /api/ { auth_request /oauth2/auth; - error_page 401 =401; # Pass through the 401 status + # No `error_page 401` directive: nginx returns the 401 from auth_request + # to the client unchanged, which is what API/machine clients expect. proxy_pass http://backend/; } ```