docs: caddy integration (#3307)

This adds docs on integration with Caddy.

Closes #1241

README.md

@@ -89,15 +89,15 @@ Docker or on top of [Kubernetes].
 <p align="center">
   <img src="./docs/images/logos/nginx.png" height="50"/>
   <img src="./docs/images/logos/traefik.png" height="50"/>
+  <img src="./docs/images/logos/caddy.png" height="50"/>
   <img src="./docs/images/logos/haproxy.png" height="50"/>  
   <img src="./docs/images/logos/kubernetes.png" height="50"/>
 </p>
 
 ***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/).
 
 <p align="center">
-  <img src="./docs/images/logos/caddy.png" height="50"/>
   <img src="./docs/images/logos/envoy.png" height="50"/>
 </p>
 

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

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

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

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

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

docs/home/supported-proxies.md

@@ -8,13 +8,13 @@ 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]     |   [<span class="material-icons green">check_circle</span>](../deployment/supported-proxies/nginx.md)    | [<span class="material-icons green">check_circle</span>](../deployment/deployment-kubernetes.md) |     <span class="material-icons red">cancel</span>     | <span class="material-icons green">check_circle</span> |
 | [Traefik] 1.x  | [<span class="material-icons green">check_circle</span>](../deployment/supported-proxies/traefik1.x.md) |                         <span class="material-icons orange">error</span>                         | <span class="material-icons green">check_circle</span> | <span class="material-icons green">check_circle</span> |
 | [Traefik] 2.x  | [<span class="material-icons green">check_circle</span>](../deployment/supported-proxies/traefik2.x.md) | [<span class="material-icons green">check_circle</span>](../deployment/deployment-kubernetes.md) | <span class="material-icons green">check_circle</span> | <span class="material-icons green">check_circle</span> |
 |   [HAProxy]    |  [<span class="material-icons green">check_circle</span>](../deployment/supported-proxies/haproxy.md)   |                          <span class="material-icons red">cancel</span>                          |    <span class="material-icons orange">error</span>    | <span class="material-icons green">check_circle</span> |
+| [Caddy] 2.5.1+ |   [<span class="material-icons green">check_circle</span>](../deployment/supported-proxies/caddy.md)    |                          <span class="material-icons red">cancel</span>                          | <span class="material-icons green">check_circle</span> | <span class="material-icons green">check_circle</span> |
 |    [Envoy]     |                            <span class="material-icons orange">error</span>                             |                         <span class="material-icons orange">error</span>                         |    <span class="material-icons orange">error</span>    |    <span class="material-icons orange">error</span>    |
-|[Caddy] 2.x  |<span class="material-icons orange">error</span>                                                       |<span class="material-icons red">cancel</span>                                                  |<span class="material-icons orange">error</span>      |<span class="material-icons orange">error</span>      |
 |    [Apache]    |                             <span class="material-icons red">cancel</span>                              |                          <span class="material-icons red">cancel</span>                          |     <span class="material-icons red">cancel</span>     |     <span class="material-icons red">cancel</span>     |
 |     [IIS]      |                             <span class="material-icons red">cancel</span>                              |                          <span class="material-icons red">cancel</span>                          |     <span class="material-icons red">cancel</span>     |     <span class="material-icons red">cancel</span>     |