@@ -43,7 +43,7 @@ server {
4343
4444 location / {
4545 auth_request /oauth2/auth;
46− error_page 401 =403 /oauth2/sign_in;
46+ error_page 401 = @oauth2_signin;
4747
4848 # pass information via X-User and X-Email headers to backend,
4949 # requires running with --set-xauthrequest flag
@@ -82,9 +82,76 @@ server {
8282 proxy_pass http://backend/;
8383 # or "root /path/to/site;" or "fastcgi_pass ..." etc
8484 }
85+
86+ # Named location for handling OAuth2 sign-in redirects
87+ # This ensures the browser receives a proper 302 redirect that it will follow
88+ location @oauth2_signin {
89+ return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
90+ }
91+}
92+```
93+
94+### Understanding the `error_page` redirect pattern
95+
96+The `auth_request` directive expects the authentication endpoint (`/oauth2/auth`) to return:
97+- **2xx**: Request is authenticated, allow access
98+- **401 or 403**: Request is not authenticated, deny access
99+
100+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**:
101+
102+```nginx
103+error_page 401 = @oauth2_signin;
104+
105+location @oauth2_signin {
106+ return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
85107}
86108```
87109
110+:::warning Avoid `error_page 401 =403` with sign_in
111+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).
112+
113+The named location pattern above ensures the browser receives a standard **302 redirect** that works correctly with all oauth2-proxy configurations.
114+:::
115+
116+### Browser vs API Routes
117+
118+:::important When to use redirects
119+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.
120+:::
121+
122+#### Browser-facing routes (HTML, UI)
123+
124+For interactive browser routes where users should be redirected to sign in:
125+
126+```nginx
127+location / {
128+ auth_request /oauth2/auth;
129+ error_page 401 = @oauth2_signin;
130+ proxy_pass http://backend/;
131+}
132+
133+location @oauth2_signin {
134+ return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
135+}
136+```
137+
138+#### API / Machine routes (no redirect)
139+
140+For API endpoints where clients expect a 401/403 status code (not a redirect):
141+
142+```nginx
143+location /api/ {
144+ auth_request /oauth2/auth;
145+ error_page 401 =401; # Pass through the 401 status
146+ proxy_pass http://backend/;
147+}
148+```
149+
150+This ensures:
151+- ✅ Browsers get a redirect and smooth login flow
152+- ✅ API clients fail fast with appropriate HTTP status codes
153+- ✅ `/oauth2/auth` remains a pure boolean oracle (2xx/401)
154+
88155When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
89156
90157```yaml