git.iko.soy/typeable/oauth2-proxy
on master help sign in
doc: add example for caddy v2 forward_auth (#2759)

--------- Co-authored-by: Denis Dabischa <34655672+dabde@users.noreply.github.com> Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>

commitfff5dd358f9830d838571a73edfeed2b0bf5a9eb authordabde <34655672+dabde@users.noreply.github.com> dateMon 23 Sep 2024, 16:34 (2 years ago) parentbc03445
2 files changed+72
compare with master
unifiedsplit
docs/docs/configuration/integration.md+36 docs/versioned_docs/version-7.6.x/configuration/integration.md+36
docs/docs/configuration/integration.md+36
@@ -265,6 +265,42 @@ http:
265265 - Authorization
266266```
267267
268+## Configuring for use with the caddy v2 `forward_auth` directive
269+
270+The [Caddy `forward_auth` directive](https://caddyserver.com/docs/caddyfile/directives/forward_auth) allows Caddy to authenticate requests via the `oauth2-proxy`'s `/auth`.
271+
272+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.
273+
274+**Following options need to be set on `oauth2-proxy`:**
275+- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
276+
277+```nginx
278+{{ domain }} {
279+ # define forward auth for any path under `/`, if not more specific defined
280+ forward_auth / {{ oauth.internalIP }}:4180 {
281+ uri /oauth2/auth
282+ copy_headers Authorization X-Auth-Request-User X-Auth-Request-Email
283+
284+ @error status 401
285+ handle_response @error {
286+ redir * /oauth2/sign_in?rd={scheme}://{host}{uri} 302
287+ }
288+ }
289+
290+ # define `/oauth2/*` as specific endpoint, to avoid forward auth protection to be able to use service
291+ reverse_proxy /oauth2/* {{ oauth.internalIP }}:4180 {
292+ header_up X-Real-IP {remote}
293+ header_up X-Forwarded-Proto https
294+ }
295+
296+ # unspecific reverse proxy will be protected from `forward_auth /`
297+ reverse_proxy {{ endpointIP }} {
298+ header_up X-Real-IP {remote}
299+ header_up X-Forwarded-Proto https
300+ }
301+}
302+```
303+
268304:::note
269305If 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.
270306:::
docs/versioned_docs/version-7.6.x/configuration/integration.md+36
@@ -265,6 +265,42 @@ http:
265265 - Authorization
266266```
267267
268+## Configuring for use with the caddy v2 `forward_auth` directive
269+
270+The [Caddy `forward_auth` directive](https://caddyserver.com/docs/caddyfile/directives/forward_auth) allows Caddy to authenticate requests via the `oauth2-proxy`'s `/auth`.
271+
272+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.
273+
274+**Following options need to be set on `oauth2-proxy`:**
275+- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
276+
277+```nginx
278+{{ domain }} {
279+ # define forward auth for any path under `/`, if not more specific defined
280+ forward_auth / {{ oauth.internalIP }}:4180 {
281+ uri /oauth2/auth
282+ copy_headers Authorization X-Auth-Request-User X-Auth-Request-Email
283+
284+ @error status 401
285+ handle_response @error {
286+ redir * /oauth2/sign_in?rd={scheme}://{host}{uri} 302
287+ }
288+ }
289+
290+ # define `/oauth2/*` as specific endpoint, to avoid forward auth protection to be able to use service
291+ reverse_proxy /oauth2/* {{ oauth.internalIP }}:4180 {
292+ header_up X-Real-IP {remote}
293+ header_up X-Forwarded-Proto https
294+ }
295+
296+ # unspecific reverse proxy will be protected from `forward_auth /`
297+ reverse_proxy {{ endpointIP }} {
298+ header_up X-Real-IP {remote}
299+ header_up X-Forwarded-Proto https
300+ }
301+}
302+```
303+
268304:::note
269305If 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.
270306:::