public_git
/
oauth2-proxy
mirror of https://github.com/oauth2-proxy/oauth2-proxy.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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>
This commit is contained in:
Stefan Markmann 2026-01-18 00:55:46 +01:00 committed by GitHub
parent cf5d34acf6
commit dcc7970a5f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 431 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGELOG.md
View File

@ -8,7 +8,8 @@
## Changes since v7.14.1
- [#3314](https://github.com/oauth2-proxy/oauth2-proxy/pull/3314) revert: fix: skip provider button auth only redirect (#3309)
- [#3314](https://github.com/oauth2-proxy/oauth2-proxy/pull/3314) revert: fix: skip provider button auth only redirect (#3309) (@StefanMarkmann / @tuunit)
- [#3315](https://github.com/oauth2-proxy/oauth2-proxy/pull/3315) docs: clarify browser vs API routes for nginx auth_request redirects (@StefanMarkmann)
# V7.14.1

31
contrib/local-environment/nginx.conf
View File

@ -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 {

69
docs/docs/configuration/integrations/nginx.md
View File

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

70
docs/versioned_docs/version-7.10.x/configuration/integration.md
View File

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

70
docs/versioned_docs/version-7.11.x/configuration/integration.md
View File

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

70
docs/versioned_docs/version-7.12.x/configuration/integration.md
View File

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

69
docs/versioned_docs/version-7.13.x/configuration/integrations/nginx.md
View File

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

69
docs/versioned_docs/version-7.14.x/configuration/integrations/nginx.md
View File

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