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>

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 {