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