* 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 reverts commit 9c61c49ec2.
The original fix broke nginx deployments using `auth_request`. When `/oauth2/auth` returns 302,
nginx's `auth_request` module treats this as an internal error:
[error] auth request unexpected status: 302 while sending to client
nginx then returns **500 Internal Server Error** to the browser.
> If the subrequest returns a 2xx response code, the access is allowed. If it returns 401 or 403,
> the access is denied with the corresponding error code. Any other response code returned by the
> subrequest is considered an error.
https://nginx.org/en/docs/http/ngx_http_auth_request_module.html
The nginx `auth_request` module has strict semantics (non-negotiable):
| Subrequest status | nginx behavior |
|---|---|
| 2xx | Allow request |
| 401 / 403 | Deny → trigger `error_page` |
| **Any other status** | **Internal error → 500** |
The `/oauth2/auth` endpoint is used as a **policy oracle** (yes/no decision),
not as a browser-facing endpoint. It cannot return redirects.
Any nginx deployment with:
- `skip-provider-button=true`
- Using `auth_request` directive
Will receive 500 errors instead of the expected authentication flow.
The correct fix for #334 is a **documentation update**, not a code change:
```nginx
error_page 401 = @oauth2_signin;
location @oauth2_signin {
return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
}
```
This keeps `/oauth2/auth` as a pure 401/2xx oracle and lets nginx perform the proper 302 redirect to the browser.
- Original Issue: #334
- Regression introduced in PR: #3309
Signed-off-by: Stefan Markmann <stefan@markmann.net>
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* fix: Return 302 redirect from AuthOnly when skip-provider-button is true
When SkipProviderButton is enabled and a user needs to login, the AuthOnly
endpoint now returns a 302 redirect directly to the OAuth provider instead
of returning 401.
This fixes an issue with nginx auth_request architecture where 401 triggers
error_page handling, which can break redirect flows because nginx overrides
the status code (e.g., to 403), and browsers don't follow Location headers
for non-3xx responses.
Fixes: #334
Signed-off-by: Stefan Markmann <stefan@markmann.net>
* update docs and changelog
Signed-off-by: Stefan Markmann <stefan@markmann.net>
* test: Add specific OAuth redirect assertions per code review feedback
Improve TestAuthOnlyEndpointRedirectWithSkipProviderButton to verify
that the Location header actually redirects to the OAuth provider's
authorize endpoint with required parameters (client_id, redirect_uri,
state), not just that a Location header exists.
Signed-off-by: Stefan Markmann <stefan@markmann.net>
* refactor: Flatten AuthOnly error handling structure
Move the SkipProviderButton check outside of the nested err != nil block
using an if-else structure. This makes the special case more visible and
reduces nesting depth without changing behavior.
Signed-off-by: Stefan Markmann <stefan@markmann.net>
* doc: backport to v7.14.x
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: Stefan Markmann <stefan@markmann.net>
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* docs: add Kubernetes Dashboard integration guide for Azure Entra ID
Add comprehensive documentation for integrating oauth2-proxy with
Kubernetes Dashboard on Azure Kubernetes Service (AKS) using Azure
Entra ID authentication.
Changes:
- Add new section "Kubernetes Dashboard on AKS" to ms_entra_id.md
with complete configuration examples including:
- Architecture overview and integration flow
- Alpha configuration for oauth2-proxy Helm chart
- Dashboard Ingress with proper auth annotations
- RBAC configuration (user-based and group-based)
- Troubleshooting guide for common issues
- Workload Identity (passwordless) setup
- Add reference link in integration.md pointing to the new section
for users looking for Kubernetes Dashboard integration examples
This addresses common issues users face when integrating Dashboard
with Entra ID, particularly:
- Missing Authorization header in auth-response-headers
- Insufficient buffer sizes for large Entra ID tokens
- RBAC permission configuration
- Group claims setup
Closes: oauth2-proxy/manifests#348
Signed-off-by: Pierluigi Lenoci <pierluigi.lenoci@gmail.com>
* docs: split integration.md into separate integration guides
Split the monolithic integration.md file into a structured integrations
directory with individual pages for each tool as requested by maintainer.
Changes:
- Create new docs/configuration/integrations/ directory structure
- Split content into separate files:
- nginx.md: Nginx auth_request directive configuration
- traefik.md: Traefik v2 ForwardAuth middleware setup
- caddy.md: Caddy v2 forward_auth directive configuration
- kubernetes-dashboard.md: K8s Dashboard integration (with deprecation notice)
- headlamp.md: Headlamp integration guide (recommended alternative)
- Transform integration.md into an index/overview page linking to all integrations
- Update docs/sidebars.js to use new Integration Guides category structure
The content has been preserved as-is from the original file, only
reorganized into separate files for better maintainability and
navigation. Added deprecation notice for Kubernetes Dashboard per
0ba796dce6
Addresses maintainer feedback from PR #3299
Signed-off-by: Pierluigi Lenoci <pierluigi.lenoci@gmail.com>
* fix: restore Kubernetes Dashboard tip box in nginx integration docs
Add back the tip box referencing the Kubernetes Dashboard Azure Entra ID
integration example that was present in the original integration.md file.
This ensures all content from the original file is preserved in the split
documentation structure.
Signed-off-by: Pierluigi Lenoci <pierluigi.lenoci@gmail.com>
* refactor: move Kubernetes Dashboard details to integration guide
Move the detailed Kubernetes Dashboard integration content from the
ms_entra_id provider documentation to the integrations section where
it logically belongs.
Changes:
- Move complete K8s Dashboard guide from ms_entra_id.md to
integrations/kubernetes-dashboard.md (architecture, configuration,
RBAC, troubleshooting, Workload Identity)
- Replace detailed section in ms_entra_id.md with brief reference
to integration guide
- Reorder sidebar: Headlamp before Kubernetes Dashboard
- Update integration.md index to show Headlamp first (recommended),
Dashboard last (deprecated)
This improves documentation organization by keeping integration guides
in the integrations/ directory and provider docs focused on provider
configuration.
Signed-off-by: Pierluigi Lenoci <pierluigi.lenoci@gmail.com>
* docs: move integration.md to integrations/index.md
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: Pierluigi Lenoci <pierluigi.lenoci@gmail.com>
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* docs: add Cisco Duo SSO provider documentation
Signed-off-by: Jan Larwig <jan@larwig.com>
* doc: backport to versioned docs 7.13 and fix alphabetical order of entries
Signed-off-by: Jan Larwig <jan@larwig.com>
* doc: improved clarity for the cisco duo configuration steps
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
remove color output in tests for better readability in github actions
bugfix: remove google as default provider for alpha options
fix conversion flow for toml to yaml
revert ginkgo color deactivation
revert claim- and secret source back to pointers
regenerate alpha config
Signed-off-by: Jan Larwig <jan@larwig.com>
* add new docs version 7.13.x
* update to release version v7.13.0
* doc: add release notes v7.13.0
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* Add check for constraints to the proxy endpoint
* Add tests for allowed_groups query string
* Add this feature to the changelog
* Apply suggestions from code review
Co-authored-by: Jan Larwig <jan@larwig.com>
* Use explicit key names in TestProxyAllowedGroups
* Document the query parameters on proxy endpoint
* Comment was copied from the AuthOnly handler but on closer inspection is not relevant here
replacing comment with one more relevant
---------
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* docs: clarify ingress-nginx integration and remove Lua block example for oauth2-proxy
This PR revises the integration guide for oauth2-proxy with ingress-nginx in Kubernetes:
Recommends the minimal configuration: just auth-url and auth-signin annotations.
Removes the Lua block example, as it did not work in practice despite following nginx documentation and extensive testing.
Clearly states that the official ingress-nginx external auth example is the recommended approach for most users.
Notes that advanced Lua/cookie handling is only needed for rare, advanced scenarios.
Signed-off-by: Jan Larwig <jan@larwig.com>
* doc: update 3 latest docs versions
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* fix: SourceHut documentation
- Add it to sidebar and provider index
- Fix broken link
This fixes an oversight in #2359, where I had not fully understood how
the documentation works.
Signed-off-by: Conrad Hoffmann <ch@bitfehler.net>
* fix: doc build instructions in docs/README.md
---------
Signed-off-by: Conrad Hoffmann <ch@bitfehler.net>
* bugfix: Gitaa team membership
Gitea doesn't properly fill in all the fields like GitHub,
so implement a series of fallbacks.
Signed-off-by: magic_rb <magic_rb@redalder.org>
* add changelog, documentation and fix groups list
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: magic_rb <magic_rb@redalder.org>
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* Add sensible logging flag to default setup for logger
* Fix default value flag for sensitive logging
* Remove sensitive logging changes
* Add Cidaas provider
* Update CHANGELOG.md
* Add required groups scope to defaults
* Fix tests
* Remove if block with protected resource
* Fix linting
* Adjust provider sorting, fixes
* Directly handle error return
Co-authored-by: Jan Larwig <jan@larwig.com>
* Use less deep nesting
Co-authored-by: Jan Larwig <jan@larwig.com>
* Directly handle returned error
Co-authored-by: Jan Larwig <jan@larwig.com>
* Pass provider options to Cidaas provider
Co-authored-by: Jan Larwig <jan@larwig.com>
* Add import for provider options
* Fix tests
* Fix linting
* Add Cidaas doc page
* Add Cidaas provider doc page to overview
* Fix link in docs
* Fix link in docs
* Add link to Cidaas
* fix provider order in docs and changelog position
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Teko012 <112829523+Teko012@users.noreply.github.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Kevin Kreitner <kevinkreitner@gmail.com>
* add new docs version 7.11.x
* update to release version v7.11.0
* add changelog entry for v7.11.0
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* feat: add feature support for cookie-secret-file
---------
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-Authored-By: Sandy Chen <Yuxuan.Chen@morganstanley.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* feat: Allow use more possible google admin-sdk api scopes.
* reduce cognitive complexity
Signed-off-by: Bob Du <i@bobdu.cc>
* remove unnecessary else block / indentation
Signed-off-by: Jan Larwig <jan@larwig.com>
* add changelog entry
Signed-off-by: Jan Larwig <jan@larwig.com>
* slight formatting and error message rephrasing
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: Bob Du <i@bobdu.cc>
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* Change Dex port in local-environment from 4190 to 5556
Port 4190 is blocked by standards-compliant browsers (e.g. Firefox), as per https://fetch.spec.whatwg.org/#port-blocking.
Port 5556 is used by Dex in its example config files: 745e1114f3/examples/config-dev.yaml (L50)
* Fix upstream in local-environment/oauth2-proxy.cfg
http://httpbin.localtest.me:8080 is only exposed to the host, not to httpbin Docker network.
Causes Bad Gateway before.
* Do not expose unauthenticated httpbin service in local-environment
This defeats the point of having oauth2-proxy.
It has already been misleading by causing the bug fixed in cafc6af48fc38f6fe4395fb0c7e2638bc84e6091.
It serves as a bad example: users might accidentally expose the service they're trying to protect in the first place.
* Remove unnecessary httpbin.localtest.me alias from local-environment
* Allow setting maximum number of csrf cookies, deleting the oldest if necessary
* Add a test for multiple CSRF cookies to remove the old cookie
* Add docs/changelog
* If limit is <=0 do not clear
Signed-off-by: test <bert@transtrend.com>
* Better docs
Co-authored-by: Jan Larwig <jan@larwig.com>
* direct check of option value
Co-authored-by: Jan Larwig <jan@larwig.com>
* direct use of option value
Co-authored-by: Jan Larwig <jan@larwig.com>
* sort based on clock compare vs time compare
Co-authored-by: Jan Larwig <jan@larwig.com>
* clock.Clock does not implement Compare, fix csrf cookie extraction after rename
Signed-off-by: Bert Helderman <bert@transtrend.com>
* Linter fix
* add method signature documentation and slight formatting
Signed-off-by: Jan Larwig <jan@larwig.com>
* fix: test case for csrf cookie limit and flag
Signed-off-by: Jan Larwig <jan@larwig.com>
---------
Signed-off-by: Bert Helderman <bert@transtrend.com>
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: test <bert@transtrend.com>
Co-authored-by: bh-tt <71650427+bh-tt@users.noreply.github.com>
* fix for github teams
* Update github.go
* added errorhandling
* Update github.md
* refactored GitHub provider
refactored hasOrg, hasOrgAndTeams and hasTeam into hasAccess to stay within function limit
* reverted Refactoring
* refactored github.go
- joined hasOrgAndTeamAccess into checkRestrictions
* refactored github.go
- reduced number of returns of function checkRestrictions to 4
* updated GitHub provider to accept legacy team ids
* GoFmt and golangci-lint
Formatted with GoFmt and followed recommendations of GoLint
* added Tests
added Tests for checkRestrictions.
* refactored in maintainer feedback
* Removed code, documentation and tests for legacy ids
* add changelog and update docs
---------
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* docs: clear up multiple-providers is unimplemented
Currently this configuration option is held up by #926. So users don't
assume this solution will work for them, and later find the feature is
not yet implemented -- own the shortcoming clearly.
* doc: add note about missing multi provider implementation to versioned docs
---------
Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* add new docs version 7.9.x
* update to release version v7.9.0
* doc: add changelog summary
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Jan Larwig <jan@larwig.com>
* Update Go version in devcontainer
* Add option to change response mode in authorization request
* Fix option name
* Update docs and changelog
* Rename config value to underscore
* Add unit tests for added parameter
* Move change to upcoming release
* Generate alpha config
---------
Co-authored-by: Michael Cornel <michael@stieler.it>
Stefan Markmann
github-actions[bot]
Jan Larwig
Shriya Kamat Tarcar
Pierluigi Lenoci
NirronCD
Jacob Alberty
Drew Foehn
Schmitt Paul
Vincent Privat
David Symonds
Conrad Hoffmann
Richard Brežák
jet
Kevin Kreitner
Sourav Agrawal
Sandy Chen
Bob Du
Simmo Saan
renovate[bot]
Daniel Mersch
Evan Carroll
Michael Niksa
Justin Ryan
Michael Cornel