git.iko.soy/typeable/oauth2-proxy
on master help sign in
docs: backport integrations split to v7.14.x & v7.13.x
a360cb3Jan Larwig
docs/versioned_docs/version-7.13.x/configuration/integration.mddeleted−310
compare with master
unifiedsplit
@@ -1,310 +0,0 @@
1−---
2−id: integration
3−title: Integration
4−---
5−
6−## Configuring for use with the Nginx `auth_request` directive
7−
8−**This option requires `--reverse-proxy` option to be set.**
9−
10−The [Nginx `auth_request` directive](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) allows Nginx to authenticate requests via the oauth2-proxy's `/auth` endpoint, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the request through. For example:
11−
12−```nginx
13−server {
14− listen 443 ssl;
15− server_name ...;
16− include ssl/ssl.conf;
17−
18− location /oauth2/ {
19− proxy_pass http://127.0.0.1:4180;
20− proxy_set_header Host $host;
21− proxy_set_header X-Real-IP $remote_addr;
22− proxy_set_header X-Auth-Request-Redirect $request_uri;
23− # or, if you are handling multiple domains:
24− # proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
25− }
26− location = /oauth2/auth {
27− proxy_pass http://127.0.0.1:4180;
28− proxy_set_header Host $host;
29− proxy_set_header X-Real-IP $remote_addr;
30− proxy_set_header X-Forwarded-Uri $request_uri;
31− # nginx auth_request includes headers but not body
32− proxy_set_header Content-Length "";
33− proxy_pass_request_body off;
34− }
35−
36− location / {
37− auth_request /oauth2/auth;
38− error_page 401 =403 /oauth2/sign_in;
39−
40− # pass information via X-User and X-Email headers to backend,
41− # requires running with --set-xauthrequest flag
42− auth_request_set $user $upstream_http_x_auth_request_user;
43− auth_request_set $email $upstream_http_x_auth_request_email;
44− proxy_set_header X-User $user;
45− proxy_set_header X-Email $email;
46−
47− # if you enabled --pass-access-token, this will pass the token to the backend
48− auth_request_set $token $upstream_http_x_auth_request_access_token;
49− proxy_set_header X-Access-Token $token;
50−
51− # if you enabled --cookie-refresh, this is needed for it to work with auth_request
52− auth_request_set $auth_cookie $upstream_http_set_cookie;
53− add_header Set-Cookie $auth_cookie;
54−
55− # When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
56− # limit and so the OAuth2 Proxy splits these into multiple parts.
57− # Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
58− # so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
59− auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
60−
61− # Extract the Cookie attributes from the first Set-Cookie header and append them
62− # to the second part ($upstream_cookie_* variables only contain the raw cookie content)
63− if ($auth_cookie ~* "(; .*)") {
64− set $auth_cookie_name_0 $auth_cookie;
65− set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
66− }
67−
68− # Send both Set-Cookie headers now if there was a second part
69− if ($auth_cookie_name_upstream_1) {
70− add_header Set-Cookie $auth_cookie_name_0;
71− add_header Set-Cookie $auth_cookie_name_1;
72− }
73−
74− proxy_pass http://backend/;
75− # or "root /path/to/site;" or "fastcgi_pass ..." etc
76− }
77−}
78−```
79−
80−When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
81−
82−```yaml
83−nginx.ingress.kubernetes.io/auth-url: "https://<oauth2-proxy-fqdn>/oauth2/auth"
84−nginx.ingress.kubernetes.io/auth-signin: "https://<oauth2-proxy-fqdn>/oauth2/start?rd=$escaped_request_uri"
85−```
86−
87−This minimal configuration works for standard authentication flows. Lua/cookie handling is only needed for advanced scenarios (e.g., multi-part cookies, custom session logic). See the official ingress-nginx example: https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/.
88−
89−It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
90−
91−You have to substitute *name* with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=".
92−
93−## Configuring for use with the Traefik (v2) `ForwardAuth` middleware
94−
95−**This option requires `--reverse-proxy` option to be set.**
96−
97−### ForwardAuth with 401 errors middleware
98−
99−The [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) allows Traefik to authenticate requests via the oauth2-proxy's `/oauth2/auth` endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration:
100−
101−```yaml
102−http:
103− routers:
104− a-service:
105− rule: "Host(`a-service.example.com`)"
106− service: a-service-backend
107− middlewares:
108− - oauth-errors
109− - oauth-auth
110− tls:
111− certResolver: default
112− domains:
113− - main: "example.com"
114− sans:
115− - "*.example.com"
116− oauth:
117− rule: "Host(`a-service.example.com`, `oauth.example.com`) && PathPrefix(`/oauth2/`)"
118− middlewares:
119− - auth-headers
120− service: oauth-backend
121− tls:
122− certResolver: default
123− domains:
124− - main: "example.com"
125− sans:
126− - "*.example.com"
127−
128− services:
129− a-service-backend:
130− loadBalancer:
131− servers:
132− - url: http://172.16.0.2:7555
133− oauth-backend:
134− loadBalancer:
135− servers:
136− - url: http://172.16.0.1:4180
137−
138− middlewares:
139− auth-headers:
140− headers:
141− sslRedirect: true
142− stsSeconds: 315360000
143− browserXssFilter: true
144− contentTypeNosniff: true
145− forceSTSHeader: true
146− sslHost: example.com
147− stsIncludeSubdomains: true
148− stsPreload: true
149− frameDeny: true
150− oauth-auth:
151− forwardAuth:
152− address: https://oauth.example.com/oauth2/auth
153− trustForwardHeader: true
154− oauth-errors:
155− errors:
156− status:
157− - "401-403"
158− service: oauth-backend
159− query: "/oauth2/sign_in?rd={url}"
160−```
161−
162−### ForwardAuth with static upstreams configuration
163−
164−Redirect to sign_in functionality provided without the use of `errors` middleware with [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) pointing to oauth2-proxy service's `/` endpoint
165−
166−**Following options need to be set on `oauth2-proxy`:**
167−- `--upstream=static://202`: Configures a static response for authenticated sessions
168−- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
169−
170−```yaml
171−http:
172− routers:
173− a-service-route-1:
174− rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/`)"
175− service: a-service-backend
176− middlewares:
177− - oauth-auth-redirect # redirects all unauthenticated to oauth2 signin
178− tls:
179− certResolver: default
180− domains:
181− - main: "example.com"
182− sans:
183− - "*.example.com"
184− a-service-route-2:
185− rule: "Host(`a-service.example.com`) && PathPrefix(`/no-auto-redirect`)"
186− service: a-service-backend
187− middlewares:
188− - oauth-auth-wo-redirect # unauthenticated session will return a 401
189− tls:
190− certResolver: default
191− domains:
192− - main: "example.com"
193− sans:
194− - "*.example.com"
195− services-oauth2-route:
196− rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/oauth2/`)"
197− middlewares:
198− - auth-headers
199− service: oauth-backend
200− tls:
201− certResolver: default
202− domains:
203− - main: "example.com"
204− sans:
205− - "*.example.com"
206− oauth2-proxy-route:
207− rule: "Host(`oauth.example.com`) && PathPrefix(`/`)"
208− middlewares:
209− - auth-headers
210− service: oauth-backend
211− tls:
212− certResolver: default
213− domains:
214− - main: "example.com"
215− sans:
216− - "*.example.com"
217−
218− services:
219− a-service-backend:
220− loadBalancer:
221− servers:
222− - url: http://172.16.0.2:7555
223− b-service-backend:
224− loadBalancer:
225− servers:
226− - url: http://172.16.0.3:7555
227− oauth-backend:
228− loadBalancer:
229− servers:
230− - url: http://172.16.0.1:4180
231−
232− middlewares:
233− auth-headers:
234− headers:
235− sslRedirect: true
236− stsSeconds: 315360000
237− browserXssFilter: true
238− contentTypeNosniff: true
239− forceSTSHeader: true
240− sslHost: example.com
241− stsIncludeSubdomains: true
242− stsPreload: true
243− frameDeny: true
244− oauth-auth-redirect:
245− forwardAuth:
246− address: https://oauth.example.com/
247− trustForwardHeader: true
248− authResponseHeaders:
249− - X-Auth-Request-Access-Token
250− - Authorization
251− oauth-auth-wo-redirect:
252− forwardAuth:
253− address: https://oauth.example.com/oauth2/auth
254− trustForwardHeader: true
255− authResponseHeaders:
256− - X-Auth-Request-Access-Token
257− - Authorization
258−```
259−
260−## Configuring for use with the Caddy (v2) `forward_auth` directive
261−
262−The [Caddy `forward_auth` directive](https://caddyserver.com/docs/caddyfile/directives/forward_auth) allows Caddy to authenticate requests via the `oauth2-proxy`'s `/auth`.
263−
264−This example is for a simple reverse proxy setup where the `/oauth2/` path is kept under the same domain and failed auth requests (401 status returned) will be caught and redirected to the `sign_in` endpoint.
265−
266−**Following options need to be set on `oauth2-proxy`:**
267−- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
268−
269−```nginx title="Caddyfile"
270−example.com {
271− # Requests to /oauth2/* are proxied to oauth2-proxy without authentication.
272− # You can't use `reverse_proxy /oauth2/* oauth2-proxy.internal:4180` here because the reverse_proxy directive has lower precedence than the handle directive.
273− handle /oauth2/* {
274− reverse_proxy oauth2-proxy.internal:4180 {
275− # oauth2-proxy requires the X-Real-IP and X-Forwarded-{Proto,Host,Uri} headers.
276− # The reverse_proxy directive automatically sets X-Forwarded-{For,Proto,Host} headers.
277− header_up X-Real-IP {remote_host}
278− header_up X-Forwarded-Uri {uri}
279− }
280− }
281−
282− # Requests to other paths are first processed by oauth2-proxy for authentication.
283− handle {
284− forward_auth oauth2-proxy.internal:4180 {
285− uri /oauth2/auth
286−
287− # oauth2-proxy requires the X-Real-IP and X-Forwarded-{Proto,Host,Uri} headers.
288− # The forward_auth directive automatically sets the X-Forwarded-{For,Proto,Host,Method,Uri} headers.
289− header_up X-Real-IP {remote_host}
290−
291− # If needed, you can copy headers from the oauth2-proxy response to the request sent to the upstream.
292− # Make sure to configure the --set-xauthrequest flag to enable this feature.
293− #copy_headers X-Auth-Request-User X-Auth-Request-Email
294−
295− # If oauth2-proxy returns a 401 status, redirect the client to the sign-in page.
296− @error status 401
297− handle_response @error {
298− redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
299− }
300− }
301−
302− # If oauth2-proxy returns a 2xx status, the request is then proxied to the upstream.
303− reverse_proxy upstream.internal:3000
304− }
305−}
306−```
307−
308−:::note
309−If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
310−:::
docs/versioned_docs/version-7.13.x/configuration/integrations/caddy.mdnew file+63
@@ -0,0 +1,63 @@
1+---
2+id: caddy
3+title: Caddy
4+---
5+
6+Integrate OAuth2 Proxy with Caddy v2 using the `forward_auth` directive.
7+
8+**Key features:**
9+- Simple forward_auth setup
10+- Automatic header handling
11+- Custom error handling and redirects
12+
13+## Configuring for use with the Caddy (v2) `forward_auth` directive
14+
15+The [Caddy `forward_auth` directive](https://caddyserver.com/docs/caddyfile/directives/forward_auth) allows Caddy to authenticate requests via the `oauth2-proxy`'s `/auth`.
16+
17+This example is for a simple reverse proxy setup where the `/oauth2/` path is kept under the same domain and failed auth requests (401 status returned) will be caught and redirected to the `sign_in` endpoint.
18+
19+**Following options need to be set on `oauth2-proxy`:**
20+- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
21+
22+```nginx title="Caddyfile"
23+example.com {
24+ # Requests to /oauth2/* are proxied to oauth2-proxy without authentication.
25+ # You can't use `reverse_proxy /oauth2/* oauth2-proxy.internal:4180` here because the reverse_proxy directive has lower precedence than the handle directive.
26+ handle /oauth2/* {
27+ reverse_proxy oauth2-proxy.internal:4180 {
28+ # oauth2-proxy requires the X-Real-IP and X-Forwarded-{Proto,Host,Uri} headers.
29+ # The reverse_proxy directive automatically sets X-Forwarded-{For,Proto,Host} headers.
30+ header_up X-Real-IP {remote_host}
31+ header_up X-Forwarded-Uri {uri}
32+ }
33+ }
34+
35+ # Requests to other paths are first processed by oauth2-proxy for authentication.
36+ handle {
37+ forward_auth oauth2-proxy.internal:4180 {
38+ uri /oauth2/auth
39+
40+ # oauth2-proxy requires the X-Real-IP and X-Forwarded-{Proto,Host,Uri} headers.
41+ # The forward_auth directive automatically sets the X-Forwarded-{For,Proto,Host,Method,Uri} headers.
42+ header_up X-Real-IP {remote_host}
43+
44+ # If needed, you can copy headers from the oauth2-proxy response to the request sent to the upstream.
45+ # Make sure to configure the --set-xauthrequest flag to enable this feature.
46+ #copy_headers X-Auth-Request-User X-Auth-Request-Email
47+
48+ # If oauth2-proxy returns a 401 status, redirect the client to the sign-in page.
49+ @error status 401
50+ handle_response @error {
51+ redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
52+ }
53+ }
54+
55+ # If oauth2-proxy returns a 2xx status, the request is then proxied to the upstream.
56+ reverse_proxy upstream.internal:3000
57+ }
58+}
59+```
60+
61+:::note
62+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
63+:::
docs/versioned_docs/version-7.13.x/configuration/integrations/headlamp.mdnew file+105
@@ -0,0 +1,105 @@
1+---
2+id: headlamp
3+title: Headlamp
4+---
5+
6+Modern, actively maintained Kubernetes web UI with OAuth2 Proxy integration examples.
7+
8+**Key features:**
9+- Active development and maintenance
10+- Modern, intuitive interface
11+- Multi-cluster support
12+- Plugin system
13+- Works with all OAuth2 providers
14+
15+## Configuring for use with Headlamp
16+
17+[Headlamp](https://headlamp.dev/) is a modern, user-friendly Kubernetes web UI that can be integrated with OAuth2 Proxy for authentication. This is a recommended alternative to the deprecated Kubernetes Dashboard.
18+
19+### Architecture
20+
21+```
22+User → Ingress → OAuth2 Proxy → Authentication Provider (e.g., Azure Entra ID)
23+ ↓
24+ Headlamp
25+```
26+
27+### Prerequisites
28+
29+- Kubernetes cluster (e.g., AKS, EKS, GKE, or self-hosted)
30+- Headlamp installed in the cluster
31+- OAuth2 provider configured (Azure Entra ID, Google, GitHub, etc.)
32+- Ingress controller (Nginx, Traefik, etc.)
33+
34+### Configuration Overview
35+
36+When integrating Headlamp with OAuth2 Proxy, the OAuth2 Proxy acts as a reverse proxy in front of Headlamp:
37+
38+1. User requests access to Headlamp
39+2. Ingress forwards to OAuth2 Proxy
40+3. OAuth2 Proxy authenticates the user via the OAuth2 provider
41+4. After successful authentication, OAuth2 Proxy proxies requests to Headlamp
42+5. Headlamp receives the authenticated user information via headers
43+
44+### OAuth2 Proxy Configuration
45+
46+Configure OAuth2 Proxy to proxy to the Headlamp service:
47+
48+```yaml
49+upstreamConfig:
50+ upstreams:
51+ - id: headlamp
52+ path: /
53+ uri: http://headlamp-service.headlamp-namespace.svc.cluster.local:4466
54+```
55+
56+Enable the necessary headers:
57+
58+```yaml
59+extraArgs:
60+ reverse-proxy: true
61+ pass-authorization-header: true
62+ set-xauthrequest: true
63+ email-domain: "*" # Or restrict to your organization
64+```
65+
66+### Example with Azure Entra ID on AKS
67+
68+For detailed instructions on deploying Headlamp with OAuth2 Proxy on Azure Kubernetes Service using Azure Entra ID, see the official Headlamp documentation:
69+
70+https://headlamp.dev/docs/latest/installation/in-cluster/aks-cluster-oauth/
71+
72+Key steps include:
73+
74+1. **Set up AKS with OIDC**: Enable Microsoft Entra ID authentication with Kubernetes RBAC
75+2. **Create Azure App Registration**: Configure redirect URI and create client secret
76+3. **Deploy Headlamp**: Install Headlamp via Helm in your cluster
77+4. **Deploy OAuth2 Proxy**: Configure OAuth2 Proxy with Entra ID provider settings and upstream pointing to Headlamp
78+5. **Configure Ingress**: Set up Ingress to route traffic through OAuth2 Proxy to Headlamp
79+6. **Set RBAC Policies**: Apply Kubernetes RBAC bindings based on users or groups
80+
81+### Integration with Other Providers
82+
83+The same integration pattern works with other OAuth2 providers supported by OAuth2 Proxy:
84+
85+- **Google**: Use the Google provider configuration
86+- **GitHub**: Use the GitHub provider configuration
87+- **GitLab**: Use the GitLab provider configuration
88+- **Keycloak**: Use the Keycloak OIDC provider configuration
89+- **Any OIDC Provider**: Use the generic OIDC provider configuration
90+
91+For provider-specific configuration examples, see the [OAuth Provider Configuration](../providers/index.md) documentation.
92+
93+### Benefits Over Kubernetes Dashboard
94+
95+Headlamp offers several advantages:
96+
97+- **Active Development**: Headlamp is actively maintained and developed
98+- **Modern UI**: Clean, intuitive interface with better UX
99+- **Plugin System**: Extensible with custom plugins
100+- **Multi-cluster Support**: Built-in support for managing multiple clusters
101+- **Desktop App**: Available as both web UI and desktop application
102+
103+:::note
104+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
105+:::
docs/versioned_docs/version-7.13.x/configuration/integrations/index.mdnew file+41
@@ -0,0 +1,41 @@
1+---
2+id: index
3+title: Integrations
4+---
5+
6+This section provides configuration examples for integrating OAuth2 Proxy with various reverse proxies, ingress controllers, and Kubernetes web UIs.
7+
8+## Reverse Proxies and Ingress Controllers
9+
10+OAuth2 Proxy can be integrated with popular reverse proxies and ingress controllers to add authentication to your applications:
11+
12+- [Nginx](nginx.md)
13+- [Traefik](traefik.md)
14+- [caddy](caddy.md)
15+
16+## Kubernetes Web UIs
17+
18+OAuth2 Proxy can also be used to add authentication to Kubernetes web user interfaces:
19+
20+- [Headlamp](headlamp.md) ✨ *Recommended*
21+- [Kubernetes Dashboard](kubernetes-dashboard.md) ⚠️ *Deprecated*
22+
23+:::tip
24+When integrating with Kubernetes web UIs, make sure to:
25+1. Configure the Ingress to pass the Authorization header with the bearer token
26+2. Increase buffer sizes for large OIDC tokens (especially with Azure Entra ID)
27+3. Set up appropriate Kubernetes RBAC permissions for your users or groups
28+:::
29+
30+## General Requirements
31+
32+Most integrations require the following OAuth2 Proxy configuration:
33+
34+- `--reverse-proxy=true`: Required to correctly handle `X-Forwarded-*` headers
35+- **Session storage**: For production deployments with large tokens due to a lot of claims like AD groups, use `--session-store-type=redis`
36+
37+For provider-specific configuration, see the [OAuth Provider Configuration](../providers/index.md) documentation.
38+
39+:::note
40+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
41+:::
docs/versioned_docs/version-7.13.x/configuration/integrations/kubernetes-dashboard.mdnew file+289
@@ -0,0 +1,289 @@
1+---
2+id: kubernetes-dashboard
3+title: Kubernetes Dashboard
4+---
5+
6+:::warning Deprecated Project
7+Kubernetes Dashboard has been deprecated and discontinued as of January 2025. See the [official announcement](https://github.com/kubernetes/dashboard/commit/0ba796dce6916bb6ca5da5ca0b3ab22cecfd1e18) for more information.
8+
9+You may want to consider alternative solutions such as [Headlamp](./headlamp.md).
10+:::
11+
12+## Kubernetes Dashboard on AKS with Azure Entra ID
13+
14+Integration guide for the deprecated Kubernetes Dashboard, including comprehensive Azure Entra ID configuration on AKS with detailed troubleshooting and RBAC setup.
15+
16+### Architecture
17+
18+```
19+User → Nginx Ingress → OAuth2 Proxy → Entra ID
20+ ↓
21+ Kubernetes Dashboard
22+```
23+
24+The integration flow:
25+1. Unauthenticated requests to Dashboard are intercepted by Nginx Ingress
26+2. Nginx redirects to OAuth2 Proxy for authentication
27+3. OAuth2 Proxy redirects to Entra ID login
28+4. After successful authentication, OAuth2 Proxy receives ID token from Entra ID
29+5. OAuth2 Proxy sets Authorization header with the bearer token
30+6. Nginx forwards the request with token to Kubernetes Dashboard
31+7. Dashboard validates the token and grants access based on AKS RBAC configuration
32+
33+### Prerequisites
34+
35+- AKS cluster with Entra ID integration enabled
36+- Kubernetes Dashboard installed (version 7.x or later)
37+- NGINX Ingress Controller installed
38+- Entra ID App Registration configured with:
39+ - Redirect URI: `https://your-oauth2-domain.com/oauth2/callback`
40+ - API Permissions: `openid`, `email`, `profile`
41+ - Groups claim enabled (if using group-based RBAC)
42+- Users or groups assigned appropriate Kubernetes RBAC permissions
43+
44+### Alpha Configuration Example
45+
46+Using [Alpha Configuration](../alpha_config.md) with the OAuth2 Proxy Helm chart:
47+
48+```yaml
49+alphaConfig:
50+ enabled: true
51+ configData:
52+ providers:
53+ - id: azure-entra
54+ provider: entra-id
55+ clientID: YOUR_CLIENT_ID
56+ clientSecret: YOUR_CLIENT_SECRET
57+ oidcConfig:
58+ issuerURL: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
59+ audienceClaims:
60+ - aud
61+ emailClaim: email
62+ groupsClaim: groups
63+ userIDClaim: oid
64+ scope: openid email profile
65+
66+ upstreamConfig:
67+ upstreams:
68+ - id: static
69+ path: /
70+ static: true
71+ staticCode: 200
72+
73+ # Response headers passed to Dashboard via Nginx
74+ injectResponseHeaders:
75+ - name: Authorization
76+ values:
77+ - claim: id_token
78+ prefix: "Bearer "
79+ - name: X-Auth-Request-User
80+ values:
81+ - claim: email
82+ - name: X-Auth-Request-Email
83+ values:
84+ - claim: email
85+ - name: X-Auth-Request-Groups
86+ values:
87+ - claim: groups
88+
89+ server:
90+ BindAddress: "0.0.0.0:4180"
91+
92+extraArgs:
93+ cookie-domain: ".your-domain.com"
94+ whitelist-domain: ".your-domain.com"
95+ email-domain: "*" # Or restrict to your organization
96+ skip-provider-button: true
97+ reverse-proxy: true
98+ pass-authorization-header: true
99+ set-xauthrequest: true
100+
101+sessionStorage:
102+ type: redis
103+
104+redis:
105+ enabled: true
106+ auth:
107+ enabled: true
108+
109+ingress:
110+ enabled: true
111+ className: nginx
112+ hosts:
113+ - OAuth2 Proxy.your-domain.com
114+ path: /oauth2
115+ pathType: Prefix
116+```
117+
118+### Kubernetes Dashboard Ingress
119+
120+**Critical**: The Ingress must include `Authorization` in the `auth-response-headers` annotation:
121+
122+```yaml
123+apiVersion: networking.k8s.io/v1
124+kind: Ingress
125+metadata:
126+ name: kubernetes-dashboard
127+ namespace: kubernetes-dashboard
128+ annotations:
129+ nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
130+ nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
131+
132+ # OAuth2 Proxy authentication
133+ nginx.ingress.kubernetes.io/auth-url: "https://OAuth2 Proxy.your-domain.com/oauth2/auth"
134+ nginx.ingress.kubernetes.io/auth-signin: "https://OAuth2 Proxy.your-domain.com/oauth2/start?rd=$scheme://$best_http_host$request_uri"
135+
136+ # Include Authorization header with bearer token
137+ nginx.ingress.kubernetes.io/auth-response-headers: "Authorization, X-Auth-Request-User, X-Auth-Request-Email"
138+
139+ # Buffer sizes for large tokens (Entra tokens can exceed 4KB)
140+ nginx.ingress.kubernetes.io/proxy-buffer-size: "256k"
141+ nginx.ingress.kubernetes.io/proxy-buffers-number: "4"
142+ nginx.ingress.kubernetes.io/proxy-busy-buffers-size: "256k"
143+spec:
144+ ingressClassName: nginx
145+ tls:
146+ - hosts:
147+ - dashboard.your-domain.com
148+ secretName: dashboard-tls
149+ rules:
150+ - host: dashboard.your-domain.com
151+ http:
152+ paths:
153+ - path: /
154+ pathType: Prefix
155+ backend:
156+ service:
157+ name: kubernetes-dashboard-kong-proxy
158+ port:
159+ number: 443
160+```
161+
162+### RBAC Configuration
163+
164+Assign Kubernetes permissions to Entra ID users or groups.
165+
166+**User-based:**
167+```yaml
168+apiVersion: rbac.authorization.k8s.io/v1
169+kind: ClusterRoleBinding
170+metadata:
171+ name: dashboard-user-admin
172+roleRef:
173+ apiGroup: rbac.authorization.k8s.io
174+ kind: ClusterRole
175+ name: cluster-admin
176+subjects:
177+ - kind: User
178+ name: "user@your-domain.com" # Email from Entra ID token
179+ apiGroup: rbac.authorization.k8s.io
180+```
181+
182+**Group-based (recommended):**
183+```yaml
184+apiVersion: rbac.authorization.k8s.io/v1
185+kind: ClusterRoleBinding
186+metadata:
187+ name: dashboard-admins-group
188+roleRef:
189+ apiGroup: rbac.authorization.k8s.io
190+ kind: ClusterRole
191+ name: cluster-admin
192+subjects:
193+ - kind: Group
194+ name: "YOUR_ENTRA_GROUP_OBJECT_ID" # Entra ID Group Object ID
195+ apiGroup: rbac.authorization.k8s.io
196+```
197+
198+For production, create custom roles with limited permissions instead of using `cluster-admin`.
199+
200+### Troubleshooting
201+
202+**Dashboard still asks for token after authentication**
203+
204+Verify that:
205+1. `injectResponseHeaders` in alphaConfig includes Authorization header with id_token claim
206+2. Dashboard Ingress includes `Authorization` in `auth-response-headers` annotation
207+3. Buffer sizes are sufficient for large tokens (set to 256k as shown above)
208+4. Check OAuth2 Proxy logs for successful token generation: `kubectl logs -n OAuth2 Proxy <pod-name>`
209+
210+**"Unauthorized" or "Invalid token" errors**
211+
212+Common causes:
213+1. User/group not configured in Kubernetes RBAC
214+ - Check: `kubectl get clusterrolebindings | grep <user-email>`
215+2. Token validation failed
216+ - Verify AKS Entra ID integration is enabled
217+ - Check Dashboard logs: `kubectl logs -n kubernetes-dashboard <pod-name>`
218+3. Incorrect OAuth2 Proxy configuration
219+ - Ensure `reverse-proxy: true` is set
220+ - Verify issuer URL matches your tenant
221+
222+**Groups not included in token**
223+
224+To include groups in the token:
225+1. In Entra ID App Registration, go to **Token configuration**
226+2. Add **groups claim** and select security groups
227+3. Or edit the manifest and add: `"groupMembershipClaims": "SecurityGroup"`
228+4. For 200+ groups, ensure scope includes `User.Read` for group overage handling
229+5. Verify groups appear in token: check OAuth2 Proxy logs
230+
231+**Session expires too quickly**
232+
233+Configure cookie expiration:
234+```yaml
235+extraArgs:
236+ cookie-expire: "24h"
237+ cookie-refresh: "1h"
238+```
239+
240+### Using Workload Identity (Passwordless)
241+
242+For production environments, use Workload Identity instead of client secrets:
243+
244+```yaml
245+config:
246+ clientID: "YOUR_CLIENT_ID"
247+ secretKeys: # Exclude client-secret
248+ - client-id
249+ - cookie-secret
250+ cookieSecret: "YOUR_COOKIE_SECRET"
251+
252+serviceAccount:
253+ annotations:
254+ azure.workload.identity/client-id: YOUR_CLIENT_ID
255+ azure.workload.identity/tenant-id: YOUR_TENANT_ID
256+
257+podLabels:
258+ azure.workload.identity/use: "true"
259+
260+alphaConfig:
261+ enabled: true
262+ configData:
263+ providers:
264+ - id: azure-entra
265+ provider: entra-id
266+ clientID: YOUR_CLIENT_ID
267+ oidcConfig:
268+ issuerURL: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
269+ # ... other config
270+ entraIdConfig:
271+ federatedTokenAuth: true
272+```
273+
274+This requires:
275+- AKS with OIDC issuer and Workload Identity enabled
276+- Federated identity credential configured in Entra ID App Registration
277+- Service account annotated with `azure.workload.identity/client-id`
278+
279+For detailed Workload Identity setup instructions, see the [Workload Identity section](../providers/ms_entra_id.md#workload-identity) in the Microsoft Entra ID provider documentation.
280+
281+## Integration with Other Providers
282+
283+While this guide focuses on Azure Entra ID, Kubernetes Dashboard can be integrated with other OAuth2 providers supported by OAuth2 Proxy. The key requirements remain the same:
284+
285+1. **Authorization Header**: Pass the bearer token via the `Authorization` header
286+2. **RBAC Configuration**: Configure Kubernetes RBAC for your authentication provider's users/groups
287+3. **Buffer Sizes**: Ensure adequate buffer sizes for tokens (especially important for OIDC providers)
288+
289+For provider-specific configuration examples, see the [OAuth Provider Configuration](../providers/index.md) documentation.
docs/versioned_docs/version-7.13.x/configuration/integrations/nginx.mdnew file+107
@@ -0,0 +1,107 @@
1+---
2+id: nginx
3+title: Nginx
4+---
5+
6+Configure OAuth2 Proxy with Nginx using the `auth_request` directive. Includes examples for both standalone Nginx configurations and Kubernetes ingress-nginx with annotations.
7+
8+**Key features:**
9+- Support for `auth_request` directive
10+- Kubernetes Ingress annotations
11+- Multi-part cookie handling for large tokens
12+- Session refresh support
13+
14+## Configuring for use with the Nginx `auth_request` directive
15+
16+**This option requires `--reverse-proxy` option to be set.**
17+
18+The [Nginx `auth_request` directive](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) allows Nginx to authenticate requests via the oauth2-proxy's `/auth` endpoint, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the request through. For example:
19+
20+```nginx
21+server {
22+ listen 443 ssl;
23+ server_name ...;
24+ include ssl/ssl.conf;
25+
26+ location /oauth2/ {
27+ proxy_pass http://127.0.0.1:4180;
28+ proxy_set_header Host $host;
29+ proxy_set_header X-Real-IP $remote_addr;
30+ proxy_set_header X-Auth-Request-Redirect $request_uri;
31+ # or, if you are handling multiple domains:
32+ # proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
33+ }
34+ location = /oauth2/auth {
35+ proxy_pass http://127.0.0.1:4180;
36+ proxy_set_header Host $host;
37+ proxy_set_header X-Real-IP $remote_addr;
38+ proxy_set_header X-Forwarded-Uri $request_uri;
39+ # nginx auth_request includes headers but not body
40+ proxy_set_header Content-Length "";
41+ proxy_pass_request_body off;
42+ }
43+
44+ location / {
45+ auth_request /oauth2/auth;
46+ error_page 401 =403 /oauth2/sign_in;
47+
48+ # pass information via X-User and X-Email headers to backend,
49+ # requires running with --set-xauthrequest flag
50+ auth_request_set $user $upstream_http_x_auth_request_user;
51+ auth_request_set $email $upstream_http_x_auth_request_email;
52+ proxy_set_header X-User $user;
53+ proxy_set_header X-Email $email;
54+
55+ # if you enabled --pass-access-token, this will pass the token to the backend
56+ auth_request_set $token $upstream_http_x_auth_request_access_token;
57+ proxy_set_header X-Access-Token $token;
58+
59+ # if you enabled --cookie-refresh, this is needed for it to work with auth_request
60+ auth_request_set $auth_cookie $upstream_http_set_cookie;
61+ add_header Set-Cookie $auth_cookie;
62+
63+ # When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
64+ # limit and so the OAuth2 Proxy splits these into multiple parts.
65+ # Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
66+ # so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
67+ auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
68+
69+ # Extract the Cookie attributes from the first Set-Cookie header and append them
70+ # to the second part ($upstream_cookie_* variables only contain the raw cookie content)
71+ if ($auth_cookie ~* "(; .*)") {
72+ set $auth_cookie_name_0 $auth_cookie;
73+ set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
74+ }
75+
76+ # Send both Set-Cookie headers now if there was a second part
77+ if ($auth_cookie_name_upstream_1) {
78+ add_header Set-Cookie $auth_cookie_name_0;
79+ add_header Set-Cookie $auth_cookie_name_1;
80+ }
81+
82+ proxy_pass http://backend/;
83+ # or "root /path/to/site;" or "fastcgi_pass ..." etc
84+ }
85+}
86+```
87+
88+When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
89+
90+```yaml
91+nginx.ingress.kubernetes.io/auth-url: "https://<oauth2-proxy-fqdn>/oauth2/auth"
92+nginx.ingress.kubernetes.io/auth-signin: "https://<oauth2-proxy-fqdn>/oauth2/start?rd=$escaped_request_uri"
93+```
94+
95+This minimal configuration works for standard authentication flows. Lua/cookie handling is only needed for advanced scenarios (e.g., multi-part cookies, custom session logic). See the official ingress-nginx example: https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/.
96+
97+It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
98+
99+:::tip Kubernetes Dashboard with Azure Entra ID
100+For a complete example of integrating oauth2-proxy with Kubernetes Dashboard on AKS using Azure Entra ID, including RBAC configuration and troubleshooting, see the [Kubernetes Dashboard on AKS](../providers/ms_entra_id.md#kubernetes-dashboard-on-aks) section in the Microsoft Entra ID provider documentation.
101+:::
102+
103+You have to substitute *name* with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=".
104+
105+:::note
106+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
107+:::
docs/versioned_docs/version-7.13.x/configuration/integrations/traefik.mdnew file+184
@@ -0,0 +1,184 @@
1+---
2+id: traefik
3+title: Traefik
4+---
5+
6+Set up OAuth2 Proxy with Traefik v2 using the `ForwardAuth` middleware. Includes examples for both error-based redirects and static upstream configurations.
7+
8+**Key features:**
9+- ForwardAuth middleware integration
10+- Error middleware for 401 redirects
11+- Static upstream configuration (202 responses)
12+- Dynamic file configuration examples
13+
14+
15+## Configuring for use with the Traefik (v2) `ForwardAuth` middleware
16+
17+**This option requires `--reverse-proxy` option to be set.**
18+
19+### ForwardAuth with 401 errors middleware
20+
21+The [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) allows Traefik to authenticate requests via the oauth2-proxy's `/oauth2/auth` endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration:
22+
23+```yaml
24+http:
25+ routers:
26+ a-service:
27+ rule: "Host(`a-service.example.com`)"
28+ service: a-service-backend
29+ middlewares:
30+ - oauth-errors
31+ - oauth-auth
32+ tls:
33+ certResolver: default
34+ domains:
35+ - main: "example.com"
36+ sans:
37+ - "*.example.com"
38+ oauth:
39+ rule: "Host(`a-service.example.com`, `oauth.example.com`) && PathPrefix(`/oauth2/`)"
40+ middlewares:
41+ - auth-headers
42+ service: oauth-backend
43+ tls:
44+ certResolver: default
45+ domains:
46+ - main: "example.com"
47+ sans:
48+ - "*.example.com"
49+
50+ services:
51+ a-service-backend:
52+ loadBalancer:
53+ servers:
54+ - url: http://172.16.0.2:7555
55+ oauth-backend:
56+ loadBalancer:
57+ servers:
58+ - url: http://172.16.0.1:4180
59+
60+ middlewares:
61+ auth-headers:
62+ headers:
63+ sslRedirect: true
64+ stsSeconds: 315360000
65+ browserXssFilter: true
66+ contentTypeNosniff: true
67+ forceSTSHeader: true
68+ sslHost: example.com
69+ stsIncludeSubdomains: true
70+ stsPreload: true
71+ frameDeny: true
72+ oauth-auth:
73+ forwardAuth:
74+ address: https://oauth.example.com/oauth2/auth
75+ trustForwardHeader: true
76+ oauth-errors:
77+ errors:
78+ status:
79+ - "401-403"
80+ service: oauth-backend
81+ query: "/oauth2/sign_in?rd={url}"
82+```
83+
84+### ForwardAuth with static upstreams configuration
85+
86+Redirect to sign_in functionality provided without the use of `errors` middleware with [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) pointing to oauth2-proxy service's `/` endpoint
87+
88+**Following options need to be set on `oauth2-proxy`:**
89+- `--upstream=static://202`: Configures a static response for authenticated sessions
90+- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
91+
92+```yaml
93+http:
94+ routers:
95+ a-service-route-1:
96+ rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/`)"
97+ service: a-service-backend
98+ middlewares:
99+ - oauth-auth-redirect # redirects all unauthenticated to oauth2 signin
100+ tls:
101+ certResolver: default
102+ domains:
103+ - main: "example.com"
104+ sans:
105+ - "*.example.com"
106+ a-service-route-2:
107+ rule: "Host(`a-service.example.com`) && PathPrefix(`/no-auto-redirect`)"
108+ service: a-service-backend
109+ middlewares:
110+ - oauth-auth-wo-redirect # unauthenticated session will return a 401
111+ tls:
112+ certResolver: default
113+ domains:
114+ - main: "example.com"
115+ sans:
116+ - "*.example.com"
117+ services-oauth2-route:
118+ rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/oauth2/`)"
119+ middlewares:
120+ - auth-headers
121+ service: oauth-backend
122+ tls:
123+ certResolver: default
124+ domains:
125+ - main: "example.com"
126+ sans:
127+ - "*.example.com"
128+ oauth2-proxy-route:
129+ rule: "Host(`oauth.example.com`) && PathPrefix(`/`)"
130+ middlewares:
131+ - auth-headers
132+ service: oauth-backend
133+ tls:
134+ certResolver: default
135+ domains:
136+ - main: "example.com"
137+ sans:
138+ - "*.example.com"
139+
140+ services:
141+ a-service-backend:
142+ loadBalancer:
143+ servers:
144+ - url: http://172.16.0.2:7555
145+ b-service-backend:
146+ loadBalancer:
147+ servers:
148+ - url: http://172.16.0.3:7555
149+ oauth-backend:
150+ loadBalancer:
151+ servers:
152+ - url: http://172.16.0.1:4180
153+
154+ middlewares:
155+ auth-headers:
156+ headers:
157+ sslRedirect: true
158+ stsSeconds: 315360000
159+ browserXssFilter: true
160+ contentTypeNosniff: true
161+ forceSTSHeader: true
162+ sslHost: example.com
163+ stsIncludeSubdomains: true
164+ stsPreload: true
165+ frameDeny: true
166+ oauth-auth-redirect:
167+ forwardAuth:
168+ address: https://oauth.example.com/
169+ trustForwardHeader: true
170+ authResponseHeaders:
171+ - X-Auth-Request-Access-Token
172+ - Authorization
173+ oauth-auth-wo-redirect:
174+ forwardAuth:
175+ address: https://oauth.example.com/oauth2/auth
176+ trustForwardHeader: true
177+ authResponseHeaders:
178+ - X-Auth-Request-Access-Token
179+ - Authorization
180+```
181+
182+:::note
183+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
184+:::
docs/versioned_docs/version-7.13.x/features/endpoints.md+1−1
@@ -14,7 +14,7 @@ OAuth2 Proxy responds directly to the following endpoints. All other endpoints w
14- /oauth2/start - a URL that will redirect to start the OAuth cycle
14- /oauth2/start - a URL that will redirect to start the OAuth cycle
15- /oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url.
15- /oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url.
16- /oauth2/userinfo - the URL is used to return user's email from the session in JSON format.
16- /oauth2/userinfo - the URL is used to return user's email from the session in JSON format.
17−- /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the [Nginx `auth_request` directive](../configuration/integration#configuring-for-use-with-the-nginx-auth_request-directive)
17+- /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the [Nginx `auth_request` directive](../configuration/integrations/nginx)
18- /oauth2/static/\* - stylesheets and other dependencies used in the sign_in and error pages
18- /oauth2/static/\* - stylesheets and other dependencies used in the sign_in and error pages
19
19
20### Sign out
20### Sign out
docs/versioned_docs/version-7.14.x/configuration/integration.mddeleted−310
@@ -1,310 +0,0 @@
1−---
2−id: integration
3−title: Integration
4−---
5−
6−## Configuring for use with the Nginx `auth_request` directive
7−
8−**This option requires `--reverse-proxy` option to be set.**
9−
10−The [Nginx `auth_request` directive](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) allows Nginx to authenticate requests via the oauth2-proxy's `/auth` endpoint, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the request through. For example:
11−
12−```nginx
13−server {
14− listen 443 ssl;
15− server_name ...;
16− include ssl/ssl.conf;
17−
18− location /oauth2/ {
19− proxy_pass http://127.0.0.1:4180;
20− proxy_set_header Host $host;
21− proxy_set_header X-Real-IP $remote_addr;
22− proxy_set_header X-Auth-Request-Redirect $request_uri;
23− # or, if you are handling multiple domains:
24− # proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
25− }
26− location = /oauth2/auth {
27− proxy_pass http://127.0.0.1:4180;
28− proxy_set_header Host $host;
29− proxy_set_header X-Real-IP $remote_addr;
30− proxy_set_header X-Forwarded-Uri $request_uri;
31− # nginx auth_request includes headers but not body
32− proxy_set_header Content-Length "";
33− proxy_pass_request_body off;
34− }
35−
36− location / {
37− auth_request /oauth2/auth;
38− error_page 401 =403 /oauth2/sign_in;
39−
40− # pass information via X-User and X-Email headers to backend,
41− # requires running with --set-xauthrequest flag
42− auth_request_set $user $upstream_http_x_auth_request_user;
43− auth_request_set $email $upstream_http_x_auth_request_email;
44− proxy_set_header X-User $user;
45− proxy_set_header X-Email $email;
46−
47− # if you enabled --pass-access-token, this will pass the token to the backend
48− auth_request_set $token $upstream_http_x_auth_request_access_token;
49− proxy_set_header X-Access-Token $token;
50−
51− # if you enabled --cookie-refresh, this is needed for it to work with auth_request
52− auth_request_set $auth_cookie $upstream_http_set_cookie;
53− add_header Set-Cookie $auth_cookie;
54−
55− # When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
56− # limit and so the OAuth2 Proxy splits these into multiple parts.
57− # Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
58− # so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
59− auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
60−
61− # Extract the Cookie attributes from the first Set-Cookie header and append them
62− # to the second part ($upstream_cookie_* variables only contain the raw cookie content)
63− if ($auth_cookie ~* "(; .*)") {
64− set $auth_cookie_name_0 $auth_cookie;
65− set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
66− }
67−
68− # Send both Set-Cookie headers now if there was a second part
69− if ($auth_cookie_name_upstream_1) {
70− add_header Set-Cookie $auth_cookie_name_0;
71− add_header Set-Cookie $auth_cookie_name_1;
72− }
73−
74− proxy_pass http://backend/;
75− # or "root /path/to/site;" or "fastcgi_pass ..." etc
76− }
77−}
78−```
79−
80−When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
81−
82−```yaml
83−nginx.ingress.kubernetes.io/auth-url: "https://<oauth2-proxy-fqdn>/oauth2/auth"
84−nginx.ingress.kubernetes.io/auth-signin: "https://<oauth2-proxy-fqdn>/oauth2/start?rd=$escaped_request_uri"
85−```
86−
87−This minimal configuration works for standard authentication flows. Lua/cookie handling is only needed for advanced scenarios (e.g., multi-part cookies, custom session logic). See the official ingress-nginx example: https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/.
88−
89−It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
90−
91−You have to substitute *name* with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=".
92−
93−## Configuring for use with the Traefik (v2) `ForwardAuth` middleware
94−
95−**This option requires `--reverse-proxy` option to be set.**
96−
97−### ForwardAuth with 401 errors middleware
98−
99−The [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) allows Traefik to authenticate requests via the oauth2-proxy's `/oauth2/auth` endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration:
100−
101−```yaml
102−http:
103− routers:
104− a-service:
105− rule: "Host(`a-service.example.com`)"
106− service: a-service-backend
107− middlewares:
108− - oauth-errors
109− - oauth-auth
110− tls:
111− certResolver: default
112− domains:
113− - main: "example.com"
114− sans:
115− - "*.example.com"
116− oauth:
117− rule: "Host(`a-service.example.com`, `oauth.example.com`) && PathPrefix(`/oauth2/`)"
118− middlewares:
119− - auth-headers
120− service: oauth-backend
121− tls:
122− certResolver: default
123− domains:
124− - main: "example.com"
125− sans:
126− - "*.example.com"
127−
128− services:
129− a-service-backend:
130− loadBalancer:
131− servers:
132− - url: http://172.16.0.2:7555
133− oauth-backend:
134− loadBalancer:
135− servers:
136− - url: http://172.16.0.1:4180
137−
138− middlewares:
139− auth-headers:
140− headers:
141− sslRedirect: true
142− stsSeconds: 315360000
143− browserXssFilter: true
144− contentTypeNosniff: true
145− forceSTSHeader: true
146− sslHost: example.com
147− stsIncludeSubdomains: true
148− stsPreload: true
149− frameDeny: true
150− oauth-auth:
151− forwardAuth:
152− address: https://oauth.example.com/oauth2/auth
153− trustForwardHeader: true
154− oauth-errors:
155− errors:
156− status:
157− - "401-403"
158− service: oauth-backend
159− query: "/oauth2/sign_in?rd={url}"
160−```
161−
162−### ForwardAuth with static upstreams configuration
163−
164−Redirect to sign_in functionality provided without the use of `errors` middleware with [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) pointing to oauth2-proxy service's `/` endpoint
165−
166−**Following options need to be set on `oauth2-proxy`:**
167−- `--upstream=static://202`: Configures a static response for authenticated sessions
168−- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
169−
170−```yaml
171−http:
172− routers:
173− a-service-route-1:
174− rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/`)"
175− service: a-service-backend
176− middlewares:
177− - oauth-auth-redirect # redirects all unauthenticated to oauth2 signin
178− tls:
179− certResolver: default
180− domains:
181− - main: "example.com"
182− sans:
183− - "*.example.com"
184− a-service-route-2:
185− rule: "Host(`a-service.example.com`) && PathPrefix(`/no-auto-redirect`)"
186− service: a-service-backend
187− middlewares:
188− - oauth-auth-wo-redirect # unauthenticated session will return a 401
189− tls:
190− certResolver: default
191− domains:
192− - main: "example.com"
193− sans:
194− - "*.example.com"
195− services-oauth2-route:
196− rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/oauth2/`)"
197− middlewares:
198− - auth-headers
199− service: oauth-backend
200− tls:
201− certResolver: default
202− domains:
203− - main: "example.com"
204− sans:
205− - "*.example.com"
206− oauth2-proxy-route:
207− rule: "Host(`oauth.example.com`) && PathPrefix(`/`)"
208− middlewares:
209− - auth-headers
210− service: oauth-backend
211− tls:
212− certResolver: default
213− domains:
214− - main: "example.com"
215− sans:
216− - "*.example.com"
217−
218− services:
219− a-service-backend:
220− loadBalancer:
221− servers:
222− - url: http://172.16.0.2:7555
223− b-service-backend:
224− loadBalancer:
225− servers:
226− - url: http://172.16.0.3:7555
227− oauth-backend:
228− loadBalancer:
229− servers:
230− - url: http://172.16.0.1:4180
231−
232− middlewares:
233− auth-headers:
234− headers:
235− sslRedirect: true
236− stsSeconds: 315360000
237− browserXssFilter: true
238− contentTypeNosniff: true
239− forceSTSHeader: true
240− sslHost: example.com
241− stsIncludeSubdomains: true
242− stsPreload: true
243− frameDeny: true
244− oauth-auth-redirect:
245− forwardAuth:
246− address: https://oauth.example.com/
247− trustForwardHeader: true
248− authResponseHeaders:
249− - X-Auth-Request-Access-Token
250− - Authorization
251− oauth-auth-wo-redirect:
252− forwardAuth:
253− address: https://oauth.example.com/oauth2/auth
254− trustForwardHeader: true
255− authResponseHeaders:
256− - X-Auth-Request-Access-Token
257− - Authorization
258−```
259−
260−## Configuring for use with the Caddy (v2) `forward_auth` directive
261−
262−The [Caddy `forward_auth` directive](https://caddyserver.com/docs/caddyfile/directives/forward_auth) allows Caddy to authenticate requests via the `oauth2-proxy`'s `/auth`.
263−
264−This example is for a simple reverse proxy setup where the `/oauth2/` path is kept under the same domain and failed auth requests (401 status returned) will be caught and redirected to the `sign_in` endpoint.
265−
266−**Following options need to be set on `oauth2-proxy`:**
267−- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
268−
269−```nginx title="Caddyfile"
270−example.com {
271− # Requests to /oauth2/* are proxied to oauth2-proxy without authentication.
272− # You can't use `reverse_proxy /oauth2/* oauth2-proxy.internal:4180` here because the reverse_proxy directive has lower precedence than the handle directive.
273− handle /oauth2/* {
274− reverse_proxy oauth2-proxy.internal:4180 {
275− # oauth2-proxy requires the X-Real-IP and X-Forwarded-{Proto,Host,Uri} headers.
276− # The reverse_proxy directive automatically sets X-Forwarded-{For,Proto,Host} headers.
277− header_up X-Real-IP {remote_host}
278− header_up X-Forwarded-Uri {uri}
279− }
280− }
281−
282− # Requests to other paths are first processed by oauth2-proxy for authentication.
283− handle {
284− forward_auth oauth2-proxy.internal:4180 {
285− uri /oauth2/auth
286−
287− # oauth2-proxy requires the X-Real-IP and X-Forwarded-{Proto,Host,Uri} headers.
288− # The forward_auth directive automatically sets the X-Forwarded-{For,Proto,Host,Method,Uri} headers.
289− header_up X-Real-IP {remote_host}
290−
291− # If needed, you can copy headers from the oauth2-proxy response to the request sent to the upstream.
292− # Make sure to configure the --set-xauthrequest flag to enable this feature.
293− #copy_headers X-Auth-Request-User X-Auth-Request-Email
294−
295− # If oauth2-proxy returns a 401 status, redirect the client to the sign-in page.
296− @error status 401
297− handle_response @error {
298− redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
299− }
300− }
301−
302− # If oauth2-proxy returns a 2xx status, the request is then proxied to the upstream.
303− reverse_proxy upstream.internal:3000
304− }
305−}
306−```
307−
308−:::note
309−If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
310−:::
docs/versioned_docs/version-7.14.x/configuration/integrations/caddy.mdnew file+63
@@ -0,0 +1,63 @@
1+---
2+id: caddy
3+title: Caddy
4+---
5+
6+Integrate OAuth2 Proxy with Caddy v2 using the `forward_auth` directive.
7+
8+**Key features:**
9+- Simple forward_auth setup
10+- Automatic header handling
11+- Custom error handling and redirects
12+
13+## Configuring for use with the Caddy (v2) `forward_auth` directive
14+
15+The [Caddy `forward_auth` directive](https://caddyserver.com/docs/caddyfile/directives/forward_auth) allows Caddy to authenticate requests via the `oauth2-proxy`'s `/auth`.
16+
17+This example is for a simple reverse proxy setup where the `/oauth2/` path is kept under the same domain and failed auth requests (401 status returned) will be caught and redirected to the `sign_in` endpoint.
18+
19+**Following options need to be set on `oauth2-proxy`:**
20+- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
21+
22+```nginx title="Caddyfile"
23+example.com {
24+ # Requests to /oauth2/* are proxied to oauth2-proxy without authentication.
25+ # You can't use `reverse_proxy /oauth2/* oauth2-proxy.internal:4180` here because the reverse_proxy directive has lower precedence than the handle directive.
26+ handle /oauth2/* {
27+ reverse_proxy oauth2-proxy.internal:4180 {
28+ # oauth2-proxy requires the X-Real-IP and X-Forwarded-{Proto,Host,Uri} headers.
29+ # The reverse_proxy directive automatically sets X-Forwarded-{For,Proto,Host} headers.
30+ header_up X-Real-IP {remote_host}
31+ header_up X-Forwarded-Uri {uri}
32+ }
33+ }
34+
35+ # Requests to other paths are first processed by oauth2-proxy for authentication.
36+ handle {
37+ forward_auth oauth2-proxy.internal:4180 {
38+ uri /oauth2/auth
39+
40+ # oauth2-proxy requires the X-Real-IP and X-Forwarded-{Proto,Host,Uri} headers.
41+ # The forward_auth directive automatically sets the X-Forwarded-{For,Proto,Host,Method,Uri} headers.
42+ header_up X-Real-IP {remote_host}
43+
44+ # If needed, you can copy headers from the oauth2-proxy response to the request sent to the upstream.
45+ # Make sure to configure the --set-xauthrequest flag to enable this feature.
46+ #copy_headers X-Auth-Request-User X-Auth-Request-Email
47+
48+ # If oauth2-proxy returns a 401 status, redirect the client to the sign-in page.
49+ @error status 401
50+ handle_response @error {
51+ redir * /oauth2/sign_in?rd={scheme}://{host}{uri}
52+ }
53+ }
54+
55+ # If oauth2-proxy returns a 2xx status, the request is then proxied to the upstream.
56+ reverse_proxy upstream.internal:3000
57+ }
58+}
59+```
60+
61+:::note
62+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
63+:::
docs/versioned_docs/version-7.14.x/configuration/integrations/headlamp.mdnew file+105
@@ -0,0 +1,105 @@
1+---
2+id: headlamp
3+title: Headlamp
4+---
5+
6+Modern, actively maintained Kubernetes web UI with OAuth2 Proxy integration examples.
7+
8+**Key features:**
9+- Active development and maintenance
10+- Modern, intuitive interface
11+- Multi-cluster support
12+- Plugin system
13+- Works with all OAuth2 providers
14+
15+## Configuring for use with Headlamp
16+
17+[Headlamp](https://headlamp.dev/) is a modern, user-friendly Kubernetes web UI that can be integrated with OAuth2 Proxy for authentication. This is a recommended alternative to the deprecated Kubernetes Dashboard.
18+
19+### Architecture
20+
21+```
22+User → Ingress → OAuth2 Proxy → Authentication Provider (e.g., Azure Entra ID)
23+ ↓
24+ Headlamp
25+```
26+
27+### Prerequisites
28+
29+- Kubernetes cluster (e.g., AKS, EKS, GKE, or self-hosted)
30+- Headlamp installed in the cluster
31+- OAuth2 provider configured (Azure Entra ID, Google, GitHub, etc.)
32+- Ingress controller (Nginx, Traefik, etc.)
33+
34+### Configuration Overview
35+
36+When integrating Headlamp with OAuth2 Proxy, the OAuth2 Proxy acts as a reverse proxy in front of Headlamp:
37+
38+1. User requests access to Headlamp
39+2. Ingress forwards to OAuth2 Proxy
40+3. OAuth2 Proxy authenticates the user via the OAuth2 provider
41+4. After successful authentication, OAuth2 Proxy proxies requests to Headlamp
42+5. Headlamp receives the authenticated user information via headers
43+
44+### OAuth2 Proxy Configuration
45+
46+Configure OAuth2 Proxy to proxy to the Headlamp service:
47+
48+```yaml
49+upstreamConfig:
50+ upstreams:
51+ - id: headlamp
52+ path: /
53+ uri: http://headlamp-service.headlamp-namespace.svc.cluster.local:4466
54+```
55+
56+Enable the necessary headers:
57+
58+```yaml
59+extraArgs:
60+ reverse-proxy: true
61+ pass-authorization-header: true
62+ set-xauthrequest: true
63+ email-domain: "*" # Or restrict to your organization
64+```
65+
66+### Example with Azure Entra ID on AKS
67+
68+For detailed instructions on deploying Headlamp with OAuth2 Proxy on Azure Kubernetes Service using Azure Entra ID, see the official Headlamp documentation:
69+
70+https://headlamp.dev/docs/latest/installation/in-cluster/aks-cluster-oauth/
71+
72+Key steps include:
73+
74+1. **Set up AKS with OIDC**: Enable Microsoft Entra ID authentication with Kubernetes RBAC
75+2. **Create Azure App Registration**: Configure redirect URI and create client secret
76+3. **Deploy Headlamp**: Install Headlamp via Helm in your cluster
77+4. **Deploy OAuth2 Proxy**: Configure OAuth2 Proxy with Entra ID provider settings and upstream pointing to Headlamp
78+5. **Configure Ingress**: Set up Ingress to route traffic through OAuth2 Proxy to Headlamp
79+6. **Set RBAC Policies**: Apply Kubernetes RBAC bindings based on users or groups
80+
81+### Integration with Other Providers
82+
83+The same integration pattern works with other OAuth2 providers supported by OAuth2 Proxy:
84+
85+- **Google**: Use the Google provider configuration
86+- **GitHub**: Use the GitHub provider configuration
87+- **GitLab**: Use the GitLab provider configuration
88+- **Keycloak**: Use the Keycloak OIDC provider configuration
89+- **Any OIDC Provider**: Use the generic OIDC provider configuration
90+
91+For provider-specific configuration examples, see the [OAuth Provider Configuration](../providers/index.md) documentation.
92+
93+### Benefits Over Kubernetes Dashboard
94+
95+Headlamp offers several advantages:
96+
97+- **Active Development**: Headlamp is actively maintained and developed
98+- **Modern UI**: Clean, intuitive interface with better UX
99+- **Plugin System**: Extensible with custom plugins
100+- **Multi-cluster Support**: Built-in support for managing multiple clusters
101+- **Desktop App**: Available as both web UI and desktop application
102+
103+:::note
104+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
105+:::
docs/versioned_docs/version-7.14.x/configuration/integrations/index.mdnew file+41
@@ -0,0 +1,41 @@
1+---
2+id: index
3+title: Integrations
4+---
5+
6+This section provides configuration examples for integrating OAuth2 Proxy with various reverse proxies, ingress controllers, and Kubernetes web UIs.
7+
8+## Reverse Proxies and Ingress Controllers
9+
10+OAuth2 Proxy can be integrated with popular reverse proxies and ingress controllers to add authentication to your applications:
11+
12+- [Nginx](nginx.md)
13+- [Traefik](traefik.md)
14+- [caddy](caddy.md)
15+
16+## Kubernetes Web UIs
17+
18+OAuth2 Proxy can also be used to add authentication to Kubernetes web user interfaces:
19+
20+- [Headlamp](headlamp.md) ✨ *Recommended*
21+- [Kubernetes Dashboard](kubernetes-dashboard.md) ⚠️ *Deprecated*
22+
23+:::tip
24+When integrating with Kubernetes web UIs, make sure to:
25+1. Configure the Ingress to pass the Authorization header with the bearer token
26+2. Increase buffer sizes for large OIDC tokens (especially with Azure Entra ID)
27+3. Set up appropriate Kubernetes RBAC permissions for your users or groups
28+:::
29+
30+## General Requirements
31+
32+Most integrations require the following OAuth2 Proxy configuration:
33+
34+- `--reverse-proxy=true`: Required to correctly handle `X-Forwarded-*` headers
35+- **Session storage**: For production deployments with large tokens due to a lot of claims like AD groups, use `--session-store-type=redis`
36+
37+For provider-specific configuration, see the [OAuth Provider Configuration](../providers/index.md) documentation.
38+
39+:::note
40+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
41+:::
docs/versioned_docs/version-7.14.x/configuration/integrations/kubernetes-dashboard.mdnew file+289
@@ -0,0 +1,289 @@
1+---
2+id: kubernetes-dashboard
3+title: Kubernetes Dashboard
4+---
5+
6+:::warning Deprecated Project
7+Kubernetes Dashboard has been deprecated and discontinued as of January 2025. See the [official announcement](https://github.com/kubernetes/dashboard/commit/0ba796dce6916bb6ca5da5ca0b3ab22cecfd1e18) for more information.
8+
9+You may want to consider alternative solutions such as [Headlamp](./headlamp.md).
10+:::
11+
12+## Kubernetes Dashboard on AKS with Azure Entra ID
13+
14+Integration guide for the deprecated Kubernetes Dashboard, including comprehensive Azure Entra ID configuration on AKS with detailed troubleshooting and RBAC setup.
15+
16+### Architecture
17+
18+```
19+User → Nginx Ingress → OAuth2 Proxy → Entra ID
20+ ↓
21+ Kubernetes Dashboard
22+```
23+
24+The integration flow:
25+1. Unauthenticated requests to Dashboard are intercepted by Nginx Ingress
26+2. Nginx redirects to OAuth2 Proxy for authentication
27+3. OAuth2 Proxy redirects to Entra ID login
28+4. After successful authentication, OAuth2 Proxy receives ID token from Entra ID
29+5. OAuth2 Proxy sets Authorization header with the bearer token
30+6. Nginx forwards the request with token to Kubernetes Dashboard
31+7. Dashboard validates the token and grants access based on AKS RBAC configuration
32+
33+### Prerequisites
34+
35+- AKS cluster with Entra ID integration enabled
36+- Kubernetes Dashboard installed (version 7.x or later)
37+- NGINX Ingress Controller installed
38+- Entra ID App Registration configured with:
39+ - Redirect URI: `https://your-oauth2-domain.com/oauth2/callback`
40+ - API Permissions: `openid`, `email`, `profile`
41+ - Groups claim enabled (if using group-based RBAC)
42+- Users or groups assigned appropriate Kubernetes RBAC permissions
43+
44+### Alpha Configuration Example
45+
46+Using [Alpha Configuration](../alpha_config.md) with the OAuth2 Proxy Helm chart:
47+
48+```yaml
49+alphaConfig:
50+ enabled: true
51+ configData:
52+ providers:
53+ - id: azure-entra
54+ provider: entra-id
55+ clientID: YOUR_CLIENT_ID
56+ clientSecret: YOUR_CLIENT_SECRET
57+ oidcConfig:
58+ issuerURL: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
59+ audienceClaims:
60+ - aud
61+ emailClaim: email
62+ groupsClaim: groups
63+ userIDClaim: oid
64+ scope: openid email profile
65+
66+ upstreamConfig:
67+ upstreams:
68+ - id: static
69+ path: /
70+ static: true
71+ staticCode: 200
72+
73+ # Response headers passed to Dashboard via Nginx
74+ injectResponseHeaders:
75+ - name: Authorization
76+ values:
77+ - claim: id_token
78+ prefix: "Bearer "
79+ - name: X-Auth-Request-User
80+ values:
81+ - claim: email
82+ - name: X-Auth-Request-Email
83+ values:
84+ - claim: email
85+ - name: X-Auth-Request-Groups
86+ values:
87+ - claim: groups
88+
89+ server:
90+ BindAddress: "0.0.0.0:4180"
91+
92+extraArgs:
93+ cookie-domain: ".your-domain.com"
94+ whitelist-domain: ".your-domain.com"
95+ email-domain: "*" # Or restrict to your organization
96+ skip-provider-button: true
97+ reverse-proxy: true
98+ pass-authorization-header: true
99+ set-xauthrequest: true
100+
101+sessionStorage:
102+ type: redis
103+
104+redis:
105+ enabled: true
106+ auth:
107+ enabled: true
108+
109+ingress:
110+ enabled: true
111+ className: nginx
112+ hosts:
113+ - OAuth2 Proxy.your-domain.com
114+ path: /oauth2
115+ pathType: Prefix
116+```
117+
118+### Kubernetes Dashboard Ingress
119+
120+**Critical**: The Ingress must include `Authorization` in the `auth-response-headers` annotation:
121+
122+```yaml
123+apiVersion: networking.k8s.io/v1
124+kind: Ingress
125+metadata:
126+ name: kubernetes-dashboard
127+ namespace: kubernetes-dashboard
128+ annotations:
129+ nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
130+ nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
131+
132+ # OAuth2 Proxy authentication
133+ nginx.ingress.kubernetes.io/auth-url: "https://OAuth2 Proxy.your-domain.com/oauth2/auth"
134+ nginx.ingress.kubernetes.io/auth-signin: "https://OAuth2 Proxy.your-domain.com/oauth2/start?rd=$scheme://$best_http_host$request_uri"
135+
136+ # Include Authorization header with bearer token
137+ nginx.ingress.kubernetes.io/auth-response-headers: "Authorization, X-Auth-Request-User, X-Auth-Request-Email"
138+
139+ # Buffer sizes for large tokens (Entra tokens can exceed 4KB)
140+ nginx.ingress.kubernetes.io/proxy-buffer-size: "256k"
141+ nginx.ingress.kubernetes.io/proxy-buffers-number: "4"
142+ nginx.ingress.kubernetes.io/proxy-busy-buffers-size: "256k"
143+spec:
144+ ingressClassName: nginx
145+ tls:
146+ - hosts:
147+ - dashboard.your-domain.com
148+ secretName: dashboard-tls
149+ rules:
150+ - host: dashboard.your-domain.com
151+ http:
152+ paths:
153+ - path: /
154+ pathType: Prefix
155+ backend:
156+ service:
157+ name: kubernetes-dashboard-kong-proxy
158+ port:
159+ number: 443
160+```
161+
162+### RBAC Configuration
163+
164+Assign Kubernetes permissions to Entra ID users or groups.
165+
166+**User-based:**
167+```yaml
168+apiVersion: rbac.authorization.k8s.io/v1
169+kind: ClusterRoleBinding
170+metadata:
171+ name: dashboard-user-admin
172+roleRef:
173+ apiGroup: rbac.authorization.k8s.io
174+ kind: ClusterRole
175+ name: cluster-admin
176+subjects:
177+ - kind: User
178+ name: "user@your-domain.com" # Email from Entra ID token
179+ apiGroup: rbac.authorization.k8s.io
180+```
181+
182+**Group-based (recommended):**
183+```yaml
184+apiVersion: rbac.authorization.k8s.io/v1
185+kind: ClusterRoleBinding
186+metadata:
187+ name: dashboard-admins-group
188+roleRef:
189+ apiGroup: rbac.authorization.k8s.io
190+ kind: ClusterRole
191+ name: cluster-admin
192+subjects:
193+ - kind: Group
194+ name: "YOUR_ENTRA_GROUP_OBJECT_ID" # Entra ID Group Object ID
195+ apiGroup: rbac.authorization.k8s.io
196+```
197+
198+For production, create custom roles with limited permissions instead of using `cluster-admin`.
199+
200+### Troubleshooting
201+
202+**Dashboard still asks for token after authentication**
203+
204+Verify that:
205+1. `injectResponseHeaders` in alphaConfig includes Authorization header with id_token claim
206+2. Dashboard Ingress includes `Authorization` in `auth-response-headers` annotation
207+3. Buffer sizes are sufficient for large tokens (set to 256k as shown above)
208+4. Check OAuth2 Proxy logs for successful token generation: `kubectl logs -n OAuth2 Proxy <pod-name>`
209+
210+**"Unauthorized" or "Invalid token" errors**
211+
212+Common causes:
213+1. User/group not configured in Kubernetes RBAC
214+ - Check: `kubectl get clusterrolebindings | grep <user-email>`
215+2. Token validation failed
216+ - Verify AKS Entra ID integration is enabled
217+ - Check Dashboard logs: `kubectl logs -n kubernetes-dashboard <pod-name>`
218+3. Incorrect OAuth2 Proxy configuration
219+ - Ensure `reverse-proxy: true` is set
220+ - Verify issuer URL matches your tenant
221+
222+**Groups not included in token**
223+
224+To include groups in the token:
225+1. In Entra ID App Registration, go to **Token configuration**
226+2. Add **groups claim** and select security groups
227+3. Or edit the manifest and add: `"groupMembershipClaims": "SecurityGroup"`
228+4. For 200+ groups, ensure scope includes `User.Read` for group overage handling
229+5. Verify groups appear in token: check OAuth2 Proxy logs
230+
231+**Session expires too quickly**
232+
233+Configure cookie expiration:
234+```yaml
235+extraArgs:
236+ cookie-expire: "24h"
237+ cookie-refresh: "1h"
238+```
239+
240+### Using Workload Identity (Passwordless)
241+
242+For production environments, use Workload Identity instead of client secrets:
243+
244+```yaml
245+config:
246+ clientID: "YOUR_CLIENT_ID"
247+ secretKeys: # Exclude client-secret
248+ - client-id
249+ - cookie-secret
250+ cookieSecret: "YOUR_COOKIE_SECRET"
251+
252+serviceAccount:
253+ annotations:
254+ azure.workload.identity/client-id: YOUR_CLIENT_ID
255+ azure.workload.identity/tenant-id: YOUR_TENANT_ID
256+
257+podLabels:
258+ azure.workload.identity/use: "true"
259+
260+alphaConfig:
261+ enabled: true
262+ configData:
263+ providers:
264+ - id: azure-entra
265+ provider: entra-id
266+ clientID: YOUR_CLIENT_ID
267+ oidcConfig:
268+ issuerURL: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
269+ # ... other config
270+ entraIdConfig:
271+ federatedTokenAuth: true
272+```
273+
274+This requires:
275+- AKS with OIDC issuer and Workload Identity enabled
276+- Federated identity credential configured in Entra ID App Registration
277+- Service account annotated with `azure.workload.identity/client-id`
278+
279+For detailed Workload Identity setup instructions, see the [Workload Identity section](../providers/ms_entra_id.md#workload-identity) in the Microsoft Entra ID provider documentation.
280+
281+## Integration with Other Providers
282+
283+While this guide focuses on Azure Entra ID, Kubernetes Dashboard can be integrated with other OAuth2 providers supported by OAuth2 Proxy. The key requirements remain the same:
284+
285+1. **Authorization Header**: Pass the bearer token via the `Authorization` header
286+2. **RBAC Configuration**: Configure Kubernetes RBAC for your authentication provider's users/groups
287+3. **Buffer Sizes**: Ensure adequate buffer sizes for tokens (especially important for OIDC providers)
288+
289+For provider-specific configuration examples, see the [OAuth Provider Configuration](../providers/index.md) documentation.
docs/versioned_docs/version-7.14.x/configuration/integrations/nginx.mdnew file+107
@@ -0,0 +1,107 @@
1+---
2+id: nginx
3+title: Nginx
4+---
5+
6+Configure OAuth2 Proxy with Nginx using the `auth_request` directive. Includes examples for both standalone Nginx configurations and Kubernetes ingress-nginx with annotations.
7+
8+**Key features:**
9+- Support for `auth_request` directive
10+- Kubernetes Ingress annotations
11+- Multi-part cookie handling for large tokens
12+- Session refresh support
13+
14+## Configuring for use with the Nginx `auth_request` directive
15+
16+**This option requires `--reverse-proxy` option to be set.**
17+
18+The [Nginx `auth_request` directive](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) allows Nginx to authenticate requests via the oauth2-proxy's `/auth` endpoint, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the request through. For example:
19+
20+```nginx
21+server {
22+ listen 443 ssl;
23+ server_name ...;
24+ include ssl/ssl.conf;
25+
26+ location /oauth2/ {
27+ proxy_pass http://127.0.0.1:4180;
28+ proxy_set_header Host $host;
29+ proxy_set_header X-Real-IP $remote_addr;
30+ proxy_set_header X-Auth-Request-Redirect $request_uri;
31+ # or, if you are handling multiple domains:
32+ # proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
33+ }
34+ location = /oauth2/auth {
35+ proxy_pass http://127.0.0.1:4180;
36+ proxy_set_header Host $host;
37+ proxy_set_header X-Real-IP $remote_addr;
38+ proxy_set_header X-Forwarded-Uri $request_uri;
39+ # nginx auth_request includes headers but not body
40+ proxy_set_header Content-Length "";
41+ proxy_pass_request_body off;
42+ }
43+
44+ location / {
45+ auth_request /oauth2/auth;
46+ error_page 401 =403 /oauth2/sign_in;
47+
48+ # pass information via X-User and X-Email headers to backend,
49+ # requires running with --set-xauthrequest flag
50+ auth_request_set $user $upstream_http_x_auth_request_user;
51+ auth_request_set $email $upstream_http_x_auth_request_email;
52+ proxy_set_header X-User $user;
53+ proxy_set_header X-Email $email;
54+
55+ # if you enabled --pass-access-token, this will pass the token to the backend
56+ auth_request_set $token $upstream_http_x_auth_request_access_token;
57+ proxy_set_header X-Access-Token $token;
58+
59+ # if you enabled --cookie-refresh, this is needed for it to work with auth_request
60+ auth_request_set $auth_cookie $upstream_http_set_cookie;
61+ add_header Set-Cookie $auth_cookie;
62+
63+ # When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
64+ # limit and so the OAuth2 Proxy splits these into multiple parts.
65+ # Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
66+ # so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
67+ auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
68+
69+ # Extract the Cookie attributes from the first Set-Cookie header and append them
70+ # to the second part ($upstream_cookie_* variables only contain the raw cookie content)
71+ if ($auth_cookie ~* "(; .*)") {
72+ set $auth_cookie_name_0 $auth_cookie;
73+ set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
74+ }
75+
76+ # Send both Set-Cookie headers now if there was a second part
77+ if ($auth_cookie_name_upstream_1) {
78+ add_header Set-Cookie $auth_cookie_name_0;
79+ add_header Set-Cookie $auth_cookie_name_1;
80+ }
81+
82+ proxy_pass http://backend/;
83+ # or "root /path/to/site;" or "fastcgi_pass ..." etc
84+ }
85+}
86+```
87+
88+When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
89+
90+```yaml
91+nginx.ingress.kubernetes.io/auth-url: "https://<oauth2-proxy-fqdn>/oauth2/auth"
92+nginx.ingress.kubernetes.io/auth-signin: "https://<oauth2-proxy-fqdn>/oauth2/start?rd=$escaped_request_uri"
93+```
94+
95+This minimal configuration works for standard authentication flows. Lua/cookie handling is only needed for advanced scenarios (e.g., multi-part cookies, custom session logic). See the official ingress-nginx example: https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/.
96+
97+It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
98+
99+:::tip Kubernetes Dashboard with Azure Entra ID
100+For a complete example of integrating oauth2-proxy with Kubernetes Dashboard on AKS using Azure Entra ID, including RBAC configuration and troubleshooting, see the [Kubernetes Dashboard on AKS](../providers/ms_entra_id.md#kubernetes-dashboard-on-aks) section in the Microsoft Entra ID provider documentation.
101+:::
102+
103+You have to substitute *name* with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=".
104+
105+:::note
106+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
107+:::
docs/versioned_docs/version-7.14.x/configuration/integrations/traefik.mdnew file+184
@@ -0,0 +1,184 @@
1+---
2+id: traefik
3+title: Traefik
4+---
5+
6+Set up OAuth2 Proxy with Traefik v2 using the `ForwardAuth` middleware. Includes examples for both error-based redirects and static upstream configurations.
7+
8+**Key features:**
9+- ForwardAuth middleware integration
10+- Error middleware for 401 redirects
11+- Static upstream configuration (202 responses)
12+- Dynamic file configuration examples
13+
14+
15+## Configuring for use with the Traefik (v2) `ForwardAuth` middleware
16+
17+**This option requires `--reverse-proxy` option to be set.**
18+
19+### ForwardAuth with 401 errors middleware
20+
21+The [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) allows Traefik to authenticate requests via the oauth2-proxy's `/oauth2/auth` endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration:
22+
23+```yaml
24+http:
25+ routers:
26+ a-service:
27+ rule: "Host(`a-service.example.com`)"
28+ service: a-service-backend
29+ middlewares:
30+ - oauth-errors
31+ - oauth-auth
32+ tls:
33+ certResolver: default
34+ domains:
35+ - main: "example.com"
36+ sans:
37+ - "*.example.com"
38+ oauth:
39+ rule: "Host(`a-service.example.com`, `oauth.example.com`) && PathPrefix(`/oauth2/`)"
40+ middlewares:
41+ - auth-headers
42+ service: oauth-backend
43+ tls:
44+ certResolver: default
45+ domains:
46+ - main: "example.com"
47+ sans:
48+ - "*.example.com"
49+
50+ services:
51+ a-service-backend:
52+ loadBalancer:
53+ servers:
54+ - url: http://172.16.0.2:7555
55+ oauth-backend:
56+ loadBalancer:
57+ servers:
58+ - url: http://172.16.0.1:4180
59+
60+ middlewares:
61+ auth-headers:
62+ headers:
63+ sslRedirect: true
64+ stsSeconds: 315360000
65+ browserXssFilter: true
66+ contentTypeNosniff: true
67+ forceSTSHeader: true
68+ sslHost: example.com
69+ stsIncludeSubdomains: true
70+ stsPreload: true
71+ frameDeny: true
72+ oauth-auth:
73+ forwardAuth:
74+ address: https://oauth.example.com/oauth2/auth
75+ trustForwardHeader: true
76+ oauth-errors:
77+ errors:
78+ status:
79+ - "401-403"
80+ service: oauth-backend
81+ query: "/oauth2/sign_in?rd={url}"
82+```
83+
84+### ForwardAuth with static upstreams configuration
85+
86+Redirect to sign_in functionality provided without the use of `errors` middleware with [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) pointing to oauth2-proxy service's `/` endpoint
87+
88+**Following options need to be set on `oauth2-proxy`:**
89+- `--upstream=static://202`: Configures a static response for authenticated sessions
90+- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
91+
92+```yaml
93+http:
94+ routers:
95+ a-service-route-1:
96+ rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/`)"
97+ service: a-service-backend
98+ middlewares:
99+ - oauth-auth-redirect # redirects all unauthenticated to oauth2 signin
100+ tls:
101+ certResolver: default
102+ domains:
103+ - main: "example.com"
104+ sans:
105+ - "*.example.com"
106+ a-service-route-2:
107+ rule: "Host(`a-service.example.com`) && PathPrefix(`/no-auto-redirect`)"
108+ service: a-service-backend
109+ middlewares:
110+ - oauth-auth-wo-redirect # unauthenticated session will return a 401
111+ tls:
112+ certResolver: default
113+ domains:
114+ - main: "example.com"
115+ sans:
116+ - "*.example.com"
117+ services-oauth2-route:
118+ rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/oauth2/`)"
119+ middlewares:
120+ - auth-headers
121+ service: oauth-backend
122+ tls:
123+ certResolver: default
124+ domains:
125+ - main: "example.com"
126+ sans:
127+ - "*.example.com"
128+ oauth2-proxy-route:
129+ rule: "Host(`oauth.example.com`) && PathPrefix(`/`)"
130+ middlewares:
131+ - auth-headers
132+ service: oauth-backend
133+ tls:
134+ certResolver: default
135+ domains:
136+ - main: "example.com"
137+ sans:
138+ - "*.example.com"
139+
140+ services:
141+ a-service-backend:
142+ loadBalancer:
143+ servers:
144+ - url: http://172.16.0.2:7555
145+ b-service-backend:
146+ loadBalancer:
147+ servers:
148+ - url: http://172.16.0.3:7555
149+ oauth-backend:
150+ loadBalancer:
151+ servers:
152+ - url: http://172.16.0.1:4180
153+
154+ middlewares:
155+ auth-headers:
156+ headers:
157+ sslRedirect: true
158+ stsSeconds: 315360000
159+ browserXssFilter: true
160+ contentTypeNosniff: true
161+ forceSTSHeader: true
162+ sslHost: example.com
163+ stsIncludeSubdomains: true
164+ stsPreload: true
165+ frameDeny: true
166+ oauth-auth-redirect:
167+ forwardAuth:
168+ address: https://oauth.example.com/
169+ trustForwardHeader: true
170+ authResponseHeaders:
171+ - X-Auth-Request-Access-Token
172+ - Authorization
173+ oauth-auth-wo-redirect:
174+ forwardAuth:
175+ address: https://oauth.example.com/oauth2/auth
176+ trustForwardHeader: true
177+ authResponseHeaders:
178+ - X-Auth-Request-Access-Token
179+ - Authorization
180+```
181+
182+:::note
183+If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
184+:::
docs/versioned_docs/version-7.14.x/configuration/overview.md+2−2
@@ -83,7 +83,7 @@ Provider specific options can be found on their respective subpages.
83| flag: `--approval-prompt`<br/>toml: `approval_prompt` | string | OAuth approval_prompt | `"force"` |
83| flag: `--approval-prompt`<br/>toml: `approval_prompt` | string | OAuth approval_prompt | `"force"` |
84| flag: `--backend-logout-url`<br/>toml: `backend_logout_url` | string | URL to perform backend logout, if you use `{id_token}` in the url it will be replaced by the actual `id_token` of the user session | |
84| flag: `--backend-logout-url`<br/>toml: `backend_logout_url` | string | URL to perform backend logout, if you use `{id_token}` in the url it will be replaced by the actual `id_token` of the user session | |
85| flag: `--client-id`<br/>toml: `client_id` | string | the OAuth Client ID, e.g. `"123456.apps.googleusercontent.com"` | |
85| flag: `--client-id`<br/>toml: `client_id` | string | the OAuth Client ID, e.g. `"123456.apps.googleusercontent.com"` | |
86−| flag: `--client-secret-file`<br/>toml: `client_secret_file` | string | the file with OAuth Client Secret | |
86+| flag: `--client-secret-file`<br/>toml: `client_secret_file` | string | the file with OAuth Client Secret. The file must contain the secret only, with no trailing newline | |
87| flag: `--client-secret`<br/>toml: `client_secret` | string | the OAuth Client Secret | |
87| flag: `--client-secret`<br/>toml: `client_secret` | string | the OAuth Client Secret | |
88| flag: `--code-challenge-method`<br/>toml: `code_challenge_method` | string | use PKCE code challenges with the specified method. Either 'plain' or 'S256' (recommended) | |
88| flag: `--code-challenge-method`<br/>toml: `code_challenge_method` | string | use PKCE code challenges with the specified method. Either 'plain' or 'S256' (recommended) | |
89| flag: `--insecure-oidc-allow-unverified-email`<br/>toml: `insecure_oidc_allow_unverified_email` | bool | don't fail if an email address in an id_token is not verified | false |
89| flag: `--insecure-oidc-allow-unverified-email`<br/>toml: `insecure_oidc_allow_unverified_email` | bool | don't fail if an email address in an id_token is not verified | false |
@@ -128,7 +128,7 @@ Provider specific options can be found on their respective subpages.
128| flag: `--cookie-refresh`<br/>toml: `cookie_refresh` | duration | refresh the cookie after this duration; `0` to disable; not supported by all providers&nbsp;[^1] | |
128| flag: `--cookie-refresh`<br/>toml: `cookie_refresh` | duration | refresh the cookie after this duration; `0` to disable; not supported by all providers&nbsp;[^1] | |
129| flag: `--cookie-samesite`<br/>toml: `cookie_samesite` | string | set SameSite cookie attribute (`"lax"`, `"strict"`, `"none"`, or `""`). | `""` |
129| flag: `--cookie-samesite`<br/>toml: `cookie_samesite` | string | set SameSite cookie attribute (`"lax"`, `"strict"`, `"none"`, or `""`). | `""` |
130| flag: `--cookie-secret`<br/>toml: `cookie_secret` | string | the seed string for secure cookies (optionally base64 encoded) | |
130| flag: `--cookie-secret`<br/>toml: `cookie_secret` | string | the seed string for secure cookies (optionally base64 encoded) | |
131−| flag: `--cookie-secret-file`<br/>toml: `cookie_secret_file` | string | For defining a separate cookie secret file to read the encryption key from | |
131+| flag: `--cookie-secret-file`<br/>toml: `cookie_secret_file` | string | File containing the cookie secret (must be raw binary, exactly 16, 24, or 32 bytes). Use dd if=/dev/urandom bs=32 count=1 > cookie.secret to generate | |
132| flag: `--cookie-secure`<br/>toml: `cookie_secure` | bool | set [secure (HTTPS only) cookie flag](https://owasp.org/www-community/controls/SecureFlag) | true |
132| flag: `--cookie-secure`<br/>toml: `cookie_secure` | bool | set [secure (HTTPS only) cookie flag](https://owasp.org/www-community/controls/SecureFlag) | true |
133
133
134[^1]: The following providers support `--cookie-refresh`: ADFS, Azure, GitLab, Google, Keycloak and all other Identity Providers which support the full [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens)
134[^1]: The following providers support `--cookie-refresh`: ADFS, Azure, GitLab, Google, Keycloak and all other Identity Providers which support the full [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens)
docs/versioned_docs/version-7.14.x/features/endpoints.md+1−1
@@ -15,7 +15,7 @@ OAuth2 Proxy responds directly to the following endpoints. All other endpoints w
15- /oauth2/start - a URL that will redirect to start the OAuth cycle
15- /oauth2/start - a URL that will redirect to start the OAuth cycle
16- /oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url.
16- /oauth2/callback - the URL used at the end of the OAuth cycle. The oauth app will be configured with this as the callback url.
17- /oauth2/userinfo - the URL is used to return user's email from the session in JSON format.
17- /oauth2/userinfo - the URL is used to return user's email from the session in JSON format.
18−- /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the [Nginx `auth_request` directive](../configuration/integration#configuring-for-use-with-the-nginx-auth_request-directive)
18+- /oauth2/auth - only returns a 202 Accepted response or a 401 Unauthorized response; for use with the [Nginx `auth_request` directive](../configuration/integrations/nginx)
19- /oauth2/static/\* - stylesheets and other dependencies used in the sign_in and error pages
19- /oauth2/static/\* - stylesheets and other dependencies used in the sign_in and error pages
20
20
21### Sign out
21### Sign out
docs/versioned_sidebars/version-7.13.x-sidebars.json+15−1
@@ -22,7 +22,21 @@
22 "collapsed": false,
22 "collapsed": false,
23 "items": [
23 "items": [
24 "configuration/overview",
24 "configuration/overview",
25+ {
26+ "type": "category",
27+ "label": "Integration Guides",
28+ "link": {
29+ "type": "doc",
30+ "id": "configuration/integrations/index"
31+ },
32+ "items": [
33+ "configuration/integrations/nginx",
34+ "configuration/integrations/traefik",
35+ "configuration/integrations/caddy",
25− "configuration/integration",
36+ "configuration/integrations/headlamp",
37+ "configuration/integrations/kubernetes-dashboard"
38+ ]
39+ },
26 {
40 {
27 "type": "category",
41 "type": "category",
28 "label": "OAuth Provider Configuration",
42 "label": "OAuth Provider Configuration",
docs/versioned_sidebars/version-7.14.x-sidebars.json+15−1
@@ -22,7 +22,21 @@
22 "collapsed": false,
22 "collapsed": false,
23 "items": [
23 "items": [
24 "configuration/overview",
24 "configuration/overview",
25+ {
26+ "type": "category",
27+ "label": "Integration Guides",
28+ "link": {
29+ "type": "doc",
30+ "id": "configuration/integrations/index"
31+ },
32+ "items": [
33+ "configuration/integrations/nginx",
34+ "configuration/integrations/traefik",
35+ "configuration/integrations/caddy",
25− "configuration/integration",
36+ "configuration/integrations/headlamp",
37+ "configuration/integrations/kubernetes-dashboard"
38+ ]
39+ },
26 {
40 {
27 "type": "category",
41 "type": "category",
28 "label": "OAuth Provider Configuration",
42 "label": "OAuth Provider Configuration",