docs: fix how to use skip-provider-button with proper auth redirect handling (#3315)

* 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>

* docs: clarify browser vs API routes for nginx auth_request redirects

Add new "Browser vs API Routes" section explaining:
- Use 302 redirect to /oauth2/sign_in only for browser-facing routes
- Use 401/403 without redirect for API/machine clients

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)

Signed-off-by: Stefan Markmann <stefan@markmann.net>
Signed-off-by: Jan Larwig <jan@larwig.com>

---------

Signed-off-by: Stefan Markmann <stefan@markmann.net>
Signed-off-by: Jan Larwig <jan@larwig.com>

docs/versioned_docs/version-7.10.x/configuration/integration.md

@@ -33,9 +33,15 @@ server {
     proxy_pass_request_body           off;
   }
 
+  # 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;
+  }
+
   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
@@ -77,6 +83,68 @@ server {
 }
 ```
 
+### 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

docs/versioned_docs/version-7.11.x/configuration/integration.md

@@ -33,9 +33,15 @@ server {
     proxy_pass_request_body           off;
   }
 
+  # 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;
+  }
+
   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
@@ -77,6 +83,68 @@ server {
 }
 ```
 
+### 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

docs/versioned_docs/version-7.12.x/configuration/integration.md

@@ -33,9 +33,15 @@ server {
     proxy_pass_request_body           off;
   }
 
+  # 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;
+  }
+
   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
@@ -77,6 +83,68 @@ server {
 }
 ```
 
+### 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

docs/versioned_docs/version-7.13.x/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

docs/versioned_docs/version-7.14.x/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