From fff5dd358f9830d838571a73edfeed2b0bf5a9eb Mon Sep 17 00:00:00 2001
From: dabde <34655672+dabde@users.noreply.github.com>
Date: Mon, 23 Sep 2024 16:34:08 +0200
Subject: [PATCH] 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>
---
 docs/docs/configuration/integration.md        | 36 +++++++++++++++++++
 .../configuration/integration.md              | 36 +++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/docs/docs/configuration/integration.md b/docs/docs/configuration/integration.md
index 5c955c2f..c5df4631 100644
--- a/docs/docs/configuration/integration.md
+++ b/docs/docs/configuration/integration.md
@@ -265,6 +265,42 @@ http:
           - Authorization
 ```
 
+## Configuring for use with the caddy v2 `forward_auth` directive
+
+The [Caddy `forward_auth` directive](https://caddyserver.com/docs/caddyfile/directives/forward_auth) allows Caddy to authenticate requests via the `oauth2-proxy`'s `/auth`.
+
+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.
+
+**Following options need to be set on `oauth2-proxy`:**
+- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
+
+```nginx
+{{ domain }} {
+	# define forward auth for any path under `/`, if not more specific defined
+	forward_auth / {{ oauth.internalIP }}:4180 {
+		uri /oauth2/auth
+		copy_headers Authorization X-Auth-Request-User X-Auth-Request-Email
+
+		@error status 401
+		handle_response @error {
+			redir * /oauth2/sign_in?rd={scheme}://{host}{uri} 302
+		}
+	}
+
+	# define `/oauth2/*` as specific endpoint, to avoid forward auth protection to be able to use service
+	reverse_proxy /oauth2/* {{ oauth.internalIP }}:4180 {
+		header_up X-Real-IP {remote}
+		header_up X-Forwarded-Proto https
+	}
+
+	# unspecific reverse proxy will be protected from `forward_auth /`
+	reverse_proxy {{ endpointIP }} {
+		header_up X-Real-IP {remote}
+		header_up X-Forwarded-Proto https
+	}
+}
+```
+
 :::note
 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.
 :::
diff --git a/docs/versioned_docs/version-7.6.x/configuration/integration.md b/docs/versioned_docs/version-7.6.x/configuration/integration.md
index 5c955c2f..c5df4631 100644
--- a/docs/versioned_docs/version-7.6.x/configuration/integration.md
+++ b/docs/versioned_docs/version-7.6.x/configuration/integration.md
@@ -265,6 +265,42 @@ http:
           - Authorization
 ```
 
+## Configuring for use with the caddy v2 `forward_auth` directive
+
+The [Caddy `forward_auth` directive](https://caddyserver.com/docs/caddyfile/directives/forward_auth) allows Caddy to authenticate requests via the `oauth2-proxy`'s `/auth`.
+
+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.
+
+**Following options need to be set on `oauth2-proxy`:**
+- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
+
+```nginx
+{{ domain }} {
+	# define forward auth for any path under `/`, if not more specific defined
+	forward_auth / {{ oauth.internalIP }}:4180 {
+		uri /oauth2/auth
+		copy_headers Authorization X-Auth-Request-User X-Auth-Request-Email
+
+		@error status 401
+		handle_response @error {
+			redir * /oauth2/sign_in?rd={scheme}://{host}{uri} 302
+		}
+	}
+
+	# define `/oauth2/*` as specific endpoint, to avoid forward auth protection to be able to use service
+	reverse_proxy /oauth2/* {{ oauth.internalIP }}:4180 {
+		header_up X-Real-IP {remote}
+		header_up X-Forwarded-Proto https
+	}
+
+	# unspecific reverse proxy will be protected from `forward_auth /`
+	reverse_proxy {{ endpointIP }} {
+		header_up X-Real-IP {remote}
+		header_up X-Forwarded-Proto https
+	}
+}
+```
+
 :::note
 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.
 :::