From 1060bcee063ed915436d6c33e8b190c486593aa5 Mon Sep 17 00:00:00 2001 From: James Elliott Date: Sat, 7 May 2022 09:18:28 +1000 Subject: [PATCH] docs: caddy integration (#3307) This adds docs on integration with Caddy. Closes #1241 --- README.md | 6 +- docs/deployment/supported-proxies/caddy.md | 125 ++++++++++++++++++ docs/deployment/supported-proxies/haproxy.md | 2 +- docs/deployment/supported-proxies/nginx.md | 2 +- .../supported-proxies/traefik1.x.md | 2 +- .../supported-proxies/traefik2.x.md | 2 +- docs/home/supported-proxies.md | 20 +-- 7 files changed, 142 insertions(+), 17 deletions(-) create mode 100644 docs/deployment/supported-proxies/caddy.md diff --git a/README.md b/README.md index baae7e53..4e14f5a4 100644 --- a/README.md +++ b/README.md @@ -89,15 +89,15 @@ Docker or on top of [Kubernetes].

+ - +

***Help Wanted:*** Assistance would be appreciated in getting Authelia working with -[Caddy](https://caddyserver.com/) and [Envoy](https://www.envoyproxy.io/). +[Envoy](https://www.envoyproxy.io/).

-

diff --git a/docs/deployment/supported-proxies/caddy.md b/docs/deployment/supported-proxies/caddy.md new file mode 100644 index 00000000..b453c00f --- /dev/null +++ b/docs/deployment/supported-proxies/caddy.md @@ -0,0 +1,125 @@ +--- +layout: default +title: Caddy +parent: Proxy Integration +grand_parent: Deployment +nav_order: 1 +--- + +[Caddy] is a reverse proxy supported by **Authelia**. + +_**Important:** Caddy officially supports the forward auth flow in version 2.5.1 and greater. You must be using this +version in order to use either Caddyfile. + +Authelia offers integration support for the official forward auth integration method Caddy provides, we +can't reasonably be expected to offer support for all of the different plugins that exist. + +## Configuration + +Below you will find commented examples of the following configuration: + +* Authelia portal +* Protected endpoint (Nextcloud) + +### Basic examples + +This example is the preferred example for integration with Caddy. There is an [advanced example](#advanced-example) but +we _**strongly urge**_ anyone who needs to use this for a particular reason to either reach out to us or Caddy for support +to ensure the basic example covers your use case in a secure way. + + +#### Subdomain + +```Caddyfile +authelia.example.com { + reverse_proxy authelia:9091 +} + +nextcloud.example.com { + forward_auth authelia:9091 { + uri /api/verify?rd=https://authelia.example.com + copy_headers Remote-User Remote-Groups Remote-Name Remote-Email + } + reverse_proxy nextcloud:80 +} +``` + +#### Subpath + +```Caddyfile +example.com { + @authelia path /authelia /authelia/* + handle @authelia { + reverse_proxy authelia:9091 + } + + @nextcloud path /nextcloud /nextcloud/* + handle @nextcloud { + forward_auth authelia:9091 { + uri /api/verify?rd=https://example.com/authelia + copy_headers Remote-User Remote-Groups Remote-Name Remote-Email + } + reverse_proxy nextcloud:80 + } +} +``` + +## Advanced example + +The advanced example allows for more flexible customization, however the [basic example](#basic-example) should be +preferred in _most_ situations. If you are unsure of what you're doing please don't use this method. + +_**Important:** Making a mistake when configuring the advanced example could lead to authentication bypass or errors._ + +```Caddyfile +authelia.example.com { + reverse_proxy authelia:9091 +} + +nextcloud.example.com { + route { + reverse_proxy authelia:9091 { + method GET + rewrite "/api/verify?rd=https://authelia.example.com" + + header_up X-Forwarded-Method {method} + header_up X-Forwarded-Uri {uri} + + ## If the auth request: + ## 1. Responds with a status code IN the 200-299 range. + ## Then: + ## 1. Proxy the request to the backend. + ## 2. Copy the relevant headers from the auth request and provide them to the backend. + @good status 2xx + handle_response @good { + request_header { + Remote-User {http.reverse_proxy.header.Remote-User} + Remote-Groups {http.reverse_proxy.header.Remote-Groups} + Remote-Name {http.reverse_proxy.header.Remote-Name} + Remote-Email {http.reverse_proxy.header.Remote-Email} + } + } + + ## If the auth request: + ## 1. Responds with a status code NOT IN the 200-299 range. + ## Then: + ## 1. Respond with the status code of the auth request. + ## 1. Copy the response except for several headers. + @denied { + status 1xx 3xx 4xx 5xx + } + handle_response @denied { + copy_response + copy_response_headers { + exclude Connection Keep-Alive Te Trailers Transfer-Encoding Upgrade + } + } + } + + reverse_proxy nextcloud:80 + } +} +``` + + +[Caddy]: https://caddyserver.com diff --git a/docs/deployment/supported-proxies/haproxy.md b/docs/deployment/supported-proxies/haproxy.md index c28558ca..0cde183d 100644 --- a/docs/deployment/supported-proxies/haproxy.md +++ b/docs/deployment/supported-proxies/haproxy.md @@ -3,7 +3,7 @@ layout: default title: HAProxy parent: Proxy Integration grand_parent: Deployment -nav_order: 1 +nav_order: 2 --- # HAProxy diff --git a/docs/deployment/supported-proxies/nginx.md b/docs/deployment/supported-proxies/nginx.md index 7f3b1af9..6ad5799c 100644 --- a/docs/deployment/supported-proxies/nginx.md +++ b/docs/deployment/supported-proxies/nginx.md @@ -3,7 +3,7 @@ layout: default title: NGINX parent: Proxy Integration grand_parent: Deployment -nav_order: 2 +nav_order: 3 --- # NGINX diff --git a/docs/deployment/supported-proxies/traefik1.x.md b/docs/deployment/supported-proxies/traefik1.x.md index 9164f186..20ee9dad 100644 --- a/docs/deployment/supported-proxies/traefik1.x.md +++ b/docs/deployment/supported-proxies/traefik1.x.md @@ -3,7 +3,7 @@ layout: default title: Traefik 1.x parent: Proxy Integration grand_parent: Deployment -nav_order: 3 +nav_order: 4 --- # Traefik diff --git a/docs/deployment/supported-proxies/traefik2.x.md b/docs/deployment/supported-proxies/traefik2.x.md index dfc2f582..03c38494 100644 --- a/docs/deployment/supported-proxies/traefik2.x.md +++ b/docs/deployment/supported-proxies/traefik2.x.md @@ -3,7 +3,7 @@ layout: default title: Traefik 2.x parent: Proxy Integration grand_parent: Deployment -nav_order: 3 +nav_order: 5 --- # Traefik2 diff --git a/docs/home/supported-proxies.md b/docs/home/supported-proxies.md index a7c2a09a..3b119aea 100644 --- a/docs/home/supported-proxies.md +++ b/docs/home/supported-proxies.md @@ -7,16 +7,16 @@ nav_order: 2 The following table is a support matrix for Authelia features and specific reverse proxies. -|Proxy |[Standard Support](#standard) |[Kubernetes Support](#kubernetes) |[XHR Redirect](#xhr-redirect) |[Request Method](#request-method) | -|:-----------:|:-----------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------:|:----------------------------------------------------:|:----------------------------------------------------:| -|[NGINX] |[check_circle](../deployment/supported-proxies/nginx.md) |[check_circle](../deployment/deployment-kubernetes.md)|cancel |check_circle| -|[Traefik] 1.x|[check_circle](../deployment/supported-proxies/traefik1.x.md)|error |check_circle|check_circle| -|[Traefik] 2.x|[check_circle](../deployment/supported-proxies/traefik2.x.md)|[check_circle](../deployment/deployment-kubernetes.md)|check_circle|check_circle| -|[HAProxy] |[check_circle](../deployment/supported-proxies/haproxy.md) |cancel |error |check_circle| -|[Envoy] |error |error |error |error | -|[Caddy] 2.x |error |cancel |error |error | -|[Apache] |cancel |cancel |cancel |cancel | -|[IIS] |cancel |cancel |cancel |cancel | +| Proxy | [Standard Support](#standard) | [Kubernetes Support](#kubernetes) | [XHR Redirect](#xhr-redirect) | [Request Method](#request-method) | +|:--------------:|:-------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------:|:------------------------------------------------------:|:------------------------------------------------------:| +| [NGINX] | [check_circle](../deployment/supported-proxies/nginx.md) | [check_circle](../deployment/deployment-kubernetes.md) | cancel | check_circle | +| [Traefik] 1.x | [check_circle](../deployment/supported-proxies/traefik1.x.md) | error | check_circle | check_circle | +| [Traefik] 2.x | [check_circle](../deployment/supported-proxies/traefik2.x.md) | [check_circle](../deployment/deployment-kubernetes.md) | check_circle | check_circle | +| [HAProxy] | [check_circle](../deployment/supported-proxies/haproxy.md) | cancel | error | check_circle | +| [Caddy] 2.5.1+ | [check_circle](../deployment/supported-proxies/caddy.md) | cancel | check_circle | check_circle | +| [Envoy] | error | error | error | error | +| [Apache] | cancel | cancel | cancel | cancel | +| [IIS] | cancel | cancel | cancel | cancel | check_circle *Support confirmed, additionally these icons are links to documentation for both the Standard and Kubernetes support columns*