docs: Caddy integration guide and demo examples (#2191)

dadrus · Feb 17, 2025 · 3ba8c7b · 3ba8c7b
1 parent 2b4e1c0
commit 3ba8c7b
Show file tree

Hide file tree

Showing 11 changed files with 115 additions and 8 deletions.
diff --git a/docs/content/guides/proxies/caddy.adoc b/docs/content/guides/proxies/caddy.adoc
@@ -0,0 +1,76 @@
+---
+title: "Caddy Integration"
+date: 2025-02-17T10:43:16+02:00
+draft: false
+weight: 11
+menu:
+  guides:
+    parent: "API Gateways & Proxies"
+description: This guide explains how to integrate heimdall with Caddy, an open-source web server and reverse proxy known for its automatic HTTPS and simple configuration.
+---
+
+:toc:
+
+https://caddyserver.com[Caddy] is a modern web server and reverse proxy known for its automatic HTTPS and simplicity. Heimdall can be integrated with Caddy using the https://caddyserver.com/docs/caddyfile/directives/forward_auth[forward_auth] directive. If heimdall responds with a 2XX status code, Caddy grants access and forwards the original request to the upstream service. Otherwise, the response from heimdall is returned to the client.
+
+== Prerequisites
+
+* Integration with Caddy requires heimdall being operated in link:{{< relref "/docs/concepts/operating_modes.adoc#_decision_mode" >}}[Decision Operation Mode].
+
+== Configuration Options
+
+Since Caddy offers extensive configuration options and heimdall supports multiple integration methods, you can choose any of the examples below. Each setup ensures heimdall can construct the URL of the protected backend server for rule matching purposes.
+
+In most cases, you need to configure heimdall to trust your Caddy instances by setting link:{{< relref "/docs/services/main.adoc#_trusted_proxies" >}}[trusted_proxies]. Exceptions are detailed in the sections below.
+
+=== Forward all information in `X-Forwarded-*` headers
+
+This is the simplest integration method, leveraging the `X-Forwarded-Method`, `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Forwarded-Uri` headers that Caddy automatically sets.
+
+NOTE: Proper configuration of `trusted_proxies` is mandatory when using this option to prevent spoofing of the `X-Forwarded-*` headers.
+
+[source]
+----
+# Caddyfile
+
+:9090 {
+    reverse_proxy upstream:8081
+
+    forward_auth https://heimdall:4455 { <1>
+        uri          / <2>
+        copy_headers Authorization <3>
+    }
+}
+----
+<1> Configures Caddy to authenticate requests with heimdall before proxying them to the upstream service. Directives before this line are unrelated to heimdall integration and are included for configuration completeness.
+<2> Specifies heimdall's verification endpoint. Here, `/` is used since all relevant request details are passed via `X-Forwarded-*` headers.
+<3> Ensures Caddy forwards the `Authorization` header set by heimdall to the upstream service. This value depends on your link:{{< relref "/docs/mechanisms/contextualizers.adoc" >}}[Contextualizers] and link:{{< relref "/docs/mechanisms/finalizers.adoc" >}}[Finalizers] configuration)
+
+=== Forward only the path and query information
+
+With this method, `X-Forwarded-*` headers are not used, relying solely on the standard request data. This means the original request's HTTP scheme and client IP are not available, but there is no need to configure the `trusted_proxies` property.
+
+[source]
+----
+# Caddyfile
+
+:9090 {
+    reverse_proxy upstream:8081
+
+    forward_auth https://heimdall:4455 { <1>
+        uri          {http.request.uri} <2>
+        method       {http.request.method} <3>
+        header_down  Host {http.request.hostport} <4>
+        copy_headers Authorization <5>
+    }
+}
+----
+<1> As in the previous approach, Caddy is configured to authenticate requests with heimdall before proxying them to the upstream service. Directives before this line are unrelated to heimdall integration and are included for configuration completeness.
+<2> Specifies heimdall’s verification endpoint. Unlike the previous integration method, the `uri` is set to the original request URI.
+<3> Ensures Caddy forwards the request using the same HTTP method as the original request.
+<4> Sets the `Host` header to match the original request, making it accessible to Heimdall.
+<5> Ensures Caddy forwards the `Authorization` header set by heimdall to the upstream service. This value depends on your link:{{< relref "/docs/mechanisms/contextualizers.adoc" >}}[Contextualizers] and link:{{< relref "/docs/mechanisms/finalizers.adoc" >}}[Finalizers] configuration.
+
+== Additional Resources
+
+Checkout the examples on https://github.com/dadrus/heimdall/tree/main/examples[GitHub] for a working demo.
diff --git a/docs/content/guides/proxies/contour.adoc b/docs/content/guides/proxies/contour.adoc
@@ -2,7 +2,7 @@
 title: "Contour Integration"
 date: 2023-08-02T17:10:52+02:00
 draft: false
-weight: 11
+weight: 12
 menu:
   guides:
     parent: "API Gateways & Proxies"

diff --git a/docs/content/guides/proxies/emissary.adoc b/docs/content/guides/proxies/emissary.adoc
@@ -2,7 +2,7 @@
 title: "Emissary Ingress Integration"
 date: 2023-08-21T15:23:41+02:00
 draft: false
-weight: 12
+weight: 13
 menu:
   guides:
     parent: "API Gateways & Proxies"

diff --git a/docs/content/guides/proxies/envoy.adoc b/docs/content/guides/proxies/envoy.adoc
@@ -2,7 +2,7 @@
 title: "Envoy Integration"
 date: 2022-12-18T00:13:59+02:00
 draft: false
-weight: 13
+weight: 14
 menu:
   guides:
     parent: "API Gateways & Proxies"

diff --git a/docs/content/guides/proxies/envoy_gateway.adoc b/docs/content/guides/proxies/envoy_gateway.adoc
@@ -2,7 +2,7 @@
 title: "Envoy Gateway Integration"
 date: 2024-05-02T13:02:43+02:00
 draft: false
-weight: 14
+weight: 15
 menu:
   guides:
     parent: "API Gateways & Proxies"

diff --git a/docs/content/guides/proxies/haproxy.adoc b/docs/content/guides/proxies/haproxy.adoc
@@ -2,7 +2,7 @@
 title: "HAProxy Integration"
 date: 2023-08-08T07:32:14+02:00
 draft: false
-weight: 15
+weight: 16
 menu:
   guides:
     parent: "API Gateways & Proxies"

diff --git a/docs/content/guides/proxies/istio.adoc b/docs/content/guides/proxies/istio.adoc
@@ -2,7 +2,7 @@
 title: "Istio Service Mesh Integration"
 date: 2024-10-23T20:49:17+02:00
 draft: false
-weight: 16
+weight: 17
 menu:
   guides:
     parent: "API Gateways & Proxies"

diff --git a/docs/content/guides/proxies/nginx.adoc b/docs/content/guides/proxies/nginx.adoc
@@ -2,7 +2,7 @@
 title: "NGINX Integration"
 date: 2022-07-29T00:14:49+02:00
 draft: false
-weight: 17
+weight: 18
 menu:
   guides:
     parent: "API Gateways & Proxies"

diff --git a/docs/content/guides/proxies/traefik.adoc b/docs/content/guides/proxies/traefik.adoc
@@ -2,7 +2,7 @@
 title: "Traefik Proxy Integration"
 date: 2022-06-09T18:59:49+02:00
 draft: false
-weight: 18
+weight: 19
 menu:
   guides:
     parent: "API Gateways & Proxies"

diff --git a/examples/docker-compose/quickstarts/Caddyfile b/examples/docker-compose/quickstarts/Caddyfile
@@ -0,0 +1,21 @@
+{
+	auto_https off
+}
+
+:9090 {
+	reverse_proxy upstream:8081
+
+    # this configuration requires a secure trusted_proxies configuration in heimdall
+	forward_auth http://heimdall:4455 {
+    	uri          /
+    	copy_headers Authorization
+    }
+
+    # alternative configuration without the need to configure trusted_proxies
+    #forward_auth http://heimdall:4455 {
+    #    uri          /
+    #    method       {method}
+    #    header_down  Host {http.request.hostport}
+    #    copy_headers Authorization
+    #}
+}
diff --git a/examples/docker-compose/quickstarts/docker-compose-caddy.yaml b/examples/docker-compose/quickstarts/docker-compose-caddy.yaml
@@ -0,0 +1,10 @@
+services:
+  edge-router:
+    image: caddy:2.9.1-alpine
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+
+  heimdall:
+    command: serve decision -c /etc/heimdall/config.yaml --insecure