From b034048d7d6fbf105f3c00f1a4dea828b644b781 Mon Sep 17 00:00:00 2001 From: James Elliott Date: Thu, 1 Sep 2022 21:59:02 +1000 Subject: [PATCH] docs: update nginx example (#3795) This updates the nginx example to use set_escape_uri from the http_set_misc module. --- docs/content/en/integration/proxies/nginx.md | 199 ++++++++++++++---- .../content/en/integration/proxies/traefik.md | 2 +- 2 files changed, 164 insertions(+), 37 deletions(-) diff --git a/docs/content/en/integration/proxies/nginx.md b/docs/content/en/integration/proxies/nginx.md index 3a195e380..a9e0d8697 100644 --- a/docs/content/en/integration/proxies/nginx.md +++ b/docs/content/en/integration/proxies/nginx.md @@ -34,6 +34,8 @@ You need the following to run __Authelia__ with [NGINX]: * [NGINX] must be built with the `http_auth_request` module which is relatively common * [NGINX] must be built with the `http_realip` module which is relatively common +* [NGINX] must be built with the `http_set_misc` module or the `nginx-mod-http-set-misc` package if you want to preserve + more than one query parameter when redirected to the portal due to a limitation in [NGINX] ## Trusted Proxies @@ -50,6 +52,90 @@ configured in the `proxy.conf` file. Each `set_realip_from` directive adds a tru proxies list. Any request that comes from a source IP not in one of the configured ranges results in the header being replaced with the source IP of the client. +## Docker Compose + +The following docker compose example has various applications suitable for setting up an example environment. + +It uses the [nginx image](https://github.com/linuxserver/docker-nginx) from [linuxserver.io] which includes all of the +required modules including the `http_set_misc` module. + +It also includes the [nginx-proxy-confs](https://github.com/linuxserver/docker-mods/tree/nginx-proxy-confs) mod where +they have several configuration examples in the `/config/nginx/proxy-confs` directory. This can be omitted if desired. + +If you're looking for a more complete solution [linuxserver.io] also have an nginx container called [SWAG](./swag.md) +which includes ACME and various other useful utilities. + +{{< details "docker-compose.yaml" >}} +```yaml +--- +version: "3.8" + +networks: + net: + driver: bridge + +services: + nginx: + container_name: nginx + image: lscr.io/linuxserver/nginx + restart: unless-stopped + networks: + net: + aliases: [] + ports: + - '80:80' + - '443:443' + volumes: + - ${PWD}/data/nginx/snippets:/config/nginx/snippets:ro + - ${PWD}/data/certificates:/config/nginx/certificates:ro + - ${PWD}/data/nginx/site-confs:/config/nginx/site-confs:ro + environment: + TZ: 'Australia/Melbourne' + DOCKER_MODS: 'linuxserver/mods:nginx-proxy-confs' + authelia: + container_name: authelia + image: authelia/authelia + restart: unless-stopped + networks: + net: + aliases: [] + expose: + - 9091 + volumes: + - ${PWD}/data/authelia/config:/config + environment: + TZ: 'Australia/Melbourne' + nextcloud: + container_name: nextcloud + image: lscr.io/linuxserver/nextcloud + restart: unless-stopped + networks: + net: + aliases: [] + expose: + - 443 + volumes: + - ${PWD}/data/nextcloud/config:/config + - ${PWD}/data/nextcloud/data:/data + environment: + PUID: '1000' + PGID: '1000' + TZ: 'Australia/Melbourne' + whoami: + container_name: whoami + image: docker.io/traefik/whoami + restart: unless-stopped + networks: + net: + aliases: [] + expose: + - 80 + environment: + TZ: 'Australia/Melbourne' +... +``` +{{< /details >}} + ## Configuration Below you will find commented examples of the following configuration: @@ -71,26 +157,26 @@ Below you will find commented examples of the following configuration: This example is for using the __Authelia__ portal redirection flow on a specific endpoint. It requires you to have the [authelia-location.conf](#authelia-locationconf), [authelia-authrequest.conf](#authelia-authrequestconf), and [proxy.conf](#proxyconf) snippets. In the example these -files exist in the `/config/nginx/` directory. The `/config/nginx/ssl.conf` snippet is expected to have +files exist in the `/config/nginx/snippets/` directory. The `/config/nginx/snippets/ssl.conf` snippet is expected to have the configuration for TLS or SSL but is not included as part of the examples. -{{< details "Authelia Portal (auth.example.com.conf)" >}} +{{< details "/config/nginx/site-confs/auth.conf (Authelia Portal)" >}} ```nginx server { listen 80; - server_name auth.example.com; + server_name auth.*; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; - server_name auth.example.com; + server_name auth.*; - include /config/nginx/ssl.conf; + include /config/nginx/snippets/ssl.conf; location / { - include /config/nginx/proxy.conf; + include /config/nginx/snippets/proxy.conf; set $upstream_authelia http://authelia:9091; proxy_pass $upstream_authelia; @@ -99,28 +185,57 @@ server { ``` {{< /details >}} -{{< details "Protected Endpoint (nextcloud.example.com.conf)" >}} +{{< details "/config/nginx/site-confs/nextcloud.conf (Protected Application - Nextcloud)" >}} ```nginx server { listen 80; - server_name nextcloud.example.com; + server_name nextcloud.*; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; - server_name nextcloud.example.com; + server_name nextcloud.*; - include /config/nginx/ssl.conf; - include /config/nginx/authelia-location.conf; + include /config/nginx/snippets/ssl.conf; + include /config/nginx/snippets/authelia-location.conf; + + set $upstream http://nextcloud; location / { - include /config/nginx/proxy.conf; - include /config/nginx/authelia-authrequest.conf; + include /config/nginx/snippets/proxy.conf; + include /config/nginx/snippets/authelia-authrequest.conf; - set $upstream_nextcloud https://nextcloud; - proxy_pass $upstream_nextcloud; + proxy_pass $upstream; + } +} +``` +{{< /details >}} + +{{< details "/config/nginx/site-confs/whoami.conf (Protected Application - whoami)" >}} +```nginx +server { + listen 80; + server_name whoami.*; + + return 301 https://$server_name$request_uri; +} + +server { + listen 443 ssl http2; + server_name whoami.*; + + include /config/nginx/snippets/ssl.conf; + include /config/nginx/snippets/authelia-location.conf; + + set $upstream http://whoami; + + location / { + include /config/nginx/snippets/proxy.conf; + include /config/nginx/snippets/authelia-authrequest.conf; + + proxy_pass $upstream; } } ``` @@ -131,31 +246,31 @@ server { This example is for using HTTP basic auth on a specific endpoint. It is based on the full example above. It requires you to have the [authelia-location-basic.conf](#authelia-location-basicconf), [authelia-authrequest-basic.conf](#authelia-authrequest-basicconf), and [proxy.conf](#proxyconf) snippets. In the -example these files exist in the `/config/nginx/` directory. The `/config/nginx/ssl.conf` snippet is expected to have +example these files exist in the `/config/nginx/snippets/` directory. The `/config/nginx/snippets/ssl.conf` snippet is expected to have the configuration for TLS or SSL but is not included as part of the examples. The Authelia Portal file from the [Standard Example](#standard-example) configuration can be reused for this example as such it isn't repeated. -{{< details "Protected Endpoint (nextcloud.example.com.conf)" >}} +{{< details "/config/nginx/site-confs/nextcloud.conf (Protected Application - Nextcloud)" >}} ```nginx server { listen 80; - server_name nextcloud.example.com; + server_name nextcloud.*; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; - server_name nextcloud.example.com; + server_name nextcloud.*; - include /config/nginx/ssl.conf; - include /config/nginx/authelia-location-basic.conf; # Use the "basic" endpoint + include /config/nginx/snippets/ssl.conf; + include /config/nginx/snippets/authelia-location-basic.conf; # Use the "basic" endpoint location / { - include /config/nginx/proxy.conf; - include /config/nginx/authelia-authrequest-basic.conf; + include /config/nginx/snippets/proxy.conf; + include /config/nginx/snippets/authelia-authrequest-basic.conf; set $upstream_nextcloud https://nextcloud; proxy_pass $upstream_nextcloud; @@ -178,7 +293,7 @@ The following is an example `proxy.conf`. The important directives include the ` [Trusted Proxies](#trusted-proxies) section to understand, or set the `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Uri`, and `X-Forwarded-For` headers. -{{< details "proxy.conf" >}} +{{< details "/config/nginx/snippets/proxy.conf" >}} ```nginx ## Headers proxy_set_header Host $host; @@ -222,7 +337,7 @@ proxy_connect_timeout 360; *The following snippet is used within the `server` block of a virtual host as a supporting endpoint used by `auth_request` and is paired with [authelia-authrequest.conf](#authelia-authrequestconf).* -{{< details "authelia-location.conf" >}} +{{< details "/config/nginx/snippets/authelia-location.conf" >}} ```nginx set $upstream_authelia http://authelia:9091/api/verify; @@ -267,13 +382,18 @@ location /authelia { *The following snippet is used within a `location` block of a virtual host which uses the appropriate location block and is paired with [authelia-location.conf](#authelia-locationconf).* -{{< details "authelia-authrequest.conf" >}} +{{< details "/config/nginx/snippets/authelia-authrequest.conf" >}} ```nginx ## Send a subrequest to Authelia to verify if the user is authenticated and has permission to access the resource. auth_request /authelia; ## Set the $target_url variable based on the original request. -auth_request_set $target_url $scheme://$http_host$request_uri; + +## Comment this line if you're using nginx without the http_set_misc module. +set_escape_uri $target_url $scheme://$http_host$request_uri; + +## Uncomment this line if you're using NGINX without the http_set_misc module. +# set $target_url $scheme://$http_host$request_uri; ## Save the upstream response headers from Authelia to variables. auth_request_set $user $upstream_http_remote_user; @@ -300,7 +420,7 @@ snippet is rarely required. It's only used if you want to only allow [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) for a particular endpoint. It's recommended to use [authelia-location.conf](#authelia-locationconf) instead.* -{{< details "authelia-location-basic.conf" >}} +{{< details "/config/nginx/snippets/authelia-location-basic.conf" >}} ```nginx set $upstream_authelia http://authelia:9091/api/verify?auth=basic; @@ -348,13 +468,16 @@ required. It's only used if you want to only allow [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) for a particular endpoint. It's recommended to use [authelia-authrequest.conf](#authelia-authrequestconf) instead.* -{{< details "authelia-authrequest-basic.conf" >}} +{{< details "/config/nginx/snippets/authelia-authrequest-basic.conf" >}} ```nginx ## Send a subrequest to Authelia to verify if the user is authenticated and has permission to access the resource. auth_request /authelia-basic; -## Set the $target_url variable based on the original request. -auth_request_set $target_url $scheme://$http_host$request_uri; +## Comment this line if you're using nginx without the http_set_misc module. +set_escape_uri $target_url $scheme://$http_host$request_uri; + +## Uncomment this line if you're using NGINX without the http_set_misc module. +# set $target_url $scheme://$http_host$request_uri; ## Save the upstream response headers from Authelia to variables. auth_request_set $user $upstream_http_remote_user; @@ -378,9 +501,9 @@ snippet is rarely required. It's only used if you want to conditionally require [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) for a particular endpoint. It's recommended to use [authelia-location.conf](#authelia-locationconf) instead.* -{{< details "authelia-location-detect.conf" >}} +{{< details "/config/nginx/snippets/authelia-location-detect.conf" >}} ```nginx -include /config/nginx/authelia-location.conf; +include /config/nginx/snippets/authelia-location.conf; set $is_basic_auth ""; # false value @@ -417,13 +540,16 @@ required. It's only used if you want to conditionally require [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) for a particular endpoint. It's recommended to use [authelia-authrequest.conf](#authelia-authrequestconf) instead.* -{{< details "authelia-authrequest-detect.conf" >}} +{{< details "/config/nginx/snippets/authelia-authrequest-detect.conf" >}} ```nginx ## Send a subrequest to Authelia to verify if the user is authenticated and has permission to access the resource. auth_request /authelia; -## Set the $target_url variable based on the original request. -auth_request_set $target_url $scheme://$http_host$request_uri; +## Comment this line if you're using nginx without the http_set_misc module. +set_escape_uri $target_url $scheme://$http_host$request_uri; + +## Uncomment this line if you're using NGINX without the http_set_misc module. +# set $target_url $scheme://$http_host$request_uri; ## Save the upstream response headers from Authelia to variables. auth_request_set $user $upstream_http_remote_user; @@ -450,3 +576,4 @@ error_page 401 =302 /authelia-detect?rd=$target_url; [NGINX]: https://www.nginx.com/ [Forwarded Headers]: fowarded-headers +[linuxserver.io]: https://www.linuxserver.io/ diff --git a/docs/content/en/integration/proxies/traefik.md b/docs/content/en/integration/proxies/traefik.md index a1c40d9bb..7723ff643 100644 --- a/docs/content/en/integration/proxies/traefik.md +++ b/docs/content/en/integration/proxies/traefik.md @@ -90,7 +90,7 @@ networks: services: traefik: container_name: traefik - image: traefik:v2.6 + image: traefik:v2.8 restart: unless-stopped command: - '--api=true'