From ec4adb4aa922e2a352fec789cc8ce3d781fb2e72 Mon Sep 17 00:00:00 2001
From: Stefan Markmann <stefan@markmann.net>
Date: Sat, 17 Jan 2026 20:36:35 +0100
Subject: [PATCH] docs(nginx): Clarify auth_request redirect pattern with named
 location

Update the nginx integration documentation to recommend using a named location
(@oauth2_signin) for the error_page directive instead of the previous
'error_page 401 =403' approach.

The named location pattern ensures the browser receives a proper 302 redirect,
which is required for --skip-provider-button=true to work correctly.

The previous pattern (error_page 401 =403 /oauth2/sign_in) returned a 403
status with a Location header. Browsers do not auto-follow redirects on 403
responses, causing users to see a 'Found.' link instead of being automatically
redirected to the IdP.

Changes:
- Updated main nginx example to use @oauth2_signin named location
- Added 'Understanding the error_page redirect pattern' section
- Added warning about the limitations of 'error_page 401 =403'
- Updated local test environment (contrib/local-environment/nginx.conf)

Refs: #334
Signed-off-by: Stefan Markmann <stefan@markmann.net>
---
 contrib/local-environment/nginx.conf          | 31 +++++----
 docs/docs/configuration/integrations/nginx.md | 69 ++++++++++++++++++-
 2 files changed, 86 insertions(+), 14 deletions(-)

diff --git a/contrib/local-environment/nginx.conf b/contrib/local-environment/nginx.conf
index ffb5f8e2..15005bf6 100644
--- a/contrib/local-environment/nginx.conf
+++ b/contrib/local-environment/nginx.conf
@@ -18,17 +18,20 @@ server {
 
   auth_request /internal-auth/oauth2/auth;
 
-  # If the auth_request denies the request (401), redirect to the sign_in page
-  # and include the final rd URL back to the user's original request.
-  error_page 401 =403 http://oauth2-proxy.oauth2-proxy.localhost/oauth2/sign_in?rd=$scheme://$host$request_uri;
-
-  # Alternatively send the request to `start` to skip the provider button
-  # error_page 401 = http://oauth2-proxy.oauth2-proxy.localhost/oauth2/start?rd=$scheme://$host$request_uri;
+  # On 401, redirect to the sign_in page via a named location
+  # This ensures a proper 302 redirect that browsers will follow
+  error_page 401 = @oauth2_signin;
 
   location / {
     proxy_pass http://httpbin/;
   }
 
+  # Named location for OAuth2 sign-in redirect
+  # Returns a proper 302 that works with --skip-provider-button
+  location @oauth2_signin {
+    return 302 http://oauth2-proxy.oauth2-proxy.localhost/oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
+
   # auth_request must be a URI so this allows an internal path to then proxy to
   # the real auth_request path.
   # The trailing /'s are required so that nginx strips the prefix before proxying.
@@ -52,18 +55,20 @@ server {
   location / {
     auth_request /internal-auth/oauth2/auth;
 
-    # If the auth_request denies the request (401), redirect to the sign_in page
-    # and include the final rd URL back to the user's original request.
-    error_page 401 =403 http://oauth2-proxy.oauth2-proxy.localhost/oauth2/sign_in?rd=$scheme://$host$request_uri;
-
-    # Alternatively send the request to `start` to skip the provider button
-    # error_page 401 = http://oauth2-proxy.oauth2-proxy.localhost/oauth2/start?rd=$scheme://$host$request_uri;
-
+    # On 401, redirect to the sign_in page via a named location
+    # This ensures a proper 302 redirect that browsers will follow
+    error_page 401 = @oauth2_signin;
 
     root   /usr/share/nginx/html;
     index  index.html index.htm;
   }
 
+  # Named location for OAuth2 sign-in redirect
+  # Returns a proper 302 that works with --skip-provider-button
+  location @oauth2_signin {
+    return 302 http://oauth2-proxy.oauth2-proxy.localhost/oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
+
   # redirect server error pages to the static page /50x.html
   error_page   500 502 503 504  /50x.html;
   location = /50x.html {
diff --git a/docs/docs/configuration/integrations/nginx.md b/docs/docs/configuration/integrations/nginx.md
index a36ed762..ca6402a9 100644
--- a/docs/docs/configuration/integrations/nginx.md
+++ b/docs/docs/configuration/integrations/nginx.md
@@ -43,7 +43,7 @@ server {
 
   location / {
     auth_request /oauth2/auth;
-    error_page 401 =403 /oauth2/sign_in;
+    error_page 401 = @oauth2_signin;
 
     # pass information via X-User and X-Email headers to backend,
     # requires running with --set-xauthrequest flag
@@ -82,9 +82,76 @@ server {
     proxy_pass http://backend/;
     # or "root /path/to/site;" or "fastcgi_pass ..." etc
   }
+
+  # Named location for handling OAuth2 sign-in redirects
+  # This ensures the browser receives a proper 302 redirect that it will follow
+  location @oauth2_signin {
+    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
 }
 ```
 
+### Understanding the `error_page` redirect pattern
+
+The `auth_request` directive expects the authentication endpoint (`/oauth2/auth`) to return:
+- **2xx**: Request is authenticated, allow access
+- **401 or 403**: Request is not authenticated, deny access
+
+When a 401 is returned, nginx triggers the `error_page` directive. The recommended pattern uses a **named location** (`@oauth2_signin`) that returns a proper **302 redirect**:
+
+```nginx
+error_page 401 = @oauth2_signin;
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+:::warning Avoid `error_page 401 =403` with sign_in
+Some older configurations use `error_page 401 =403 /oauth2/sign_in`. While this works for displaying the sign-in page, it returns a **403 status code** with a `Location` header. Browsers do not automatically follow redirects on 403 responses, which can cause issues when using `--skip-provider-button=true` (users see a "Found." link instead of being automatically redirected).
+
+The named location pattern above ensures the browser receives a standard **302 redirect** that works correctly with all oauth2-proxy configurations.
+:::
+
+### Browser vs API Routes
+
+:::important When to use redirects
+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.
+:::
+
+#### Browser-facing routes (HTML, UI)
+
+For interactive browser routes where users should be redirected to sign in:
+
+```nginx
+location / {
+  auth_request /oauth2/auth;
+  error_page 401 = @oauth2_signin;
+  proxy_pass http://backend/;
+}
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+#### API / Machine routes (no redirect)
+
+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
+  proxy_pass http://backend/;
+}
+```
+
+This ensures:
+- ✅ Browsers get a redirect and smooth login flow
+- ✅ API clients fail fast with appropriate HTTP status codes
+- ✅ `/oauth2/auth` remains a pure boolean oracle (2xx/401)
+
 When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
 
 ```yaml