From 25c0b60540f7a184f8fa904987215ff19610cf98 Mon Sep 17 00:00:00 2001 From: Amir Zarrinkafsh Date: Mon, 27 Jan 2020 10:24:50 +1100 Subject: [PATCH] [MISC] Update docs to include updated proxy configuration (#580) Includes updated documentation for: * nginx * Traefik 1.x * Traefik 2.x --- docs/proxies/nginx.md | 203 ++++++++++++++++++++++++++----------- docs/proxies/traefik1.x.md | 90 ++++++++++++++++ docs/proxies/traefik2.x.md | 94 +++++++++++++++++ 3 files changed, 328 insertions(+), 59 deletions(-) create mode 100644 docs/proxies/traefik1.x.md create mode 100644 docs/proxies/traefik2.x.md diff --git a/docs/proxies/nginx.md b/docs/proxies/nginx.md index 7d1df9e74..f1b47eb38 100644 --- a/docs/proxies/nginx.md +++ b/docs/proxies/nginx.md @@ -1,82 +1,167 @@ # Nginx -[nginx] is the only official reverse proxy supported by **Authelia** for now. +[nginx] is a reverse proxy supported by **Authelia**. ## Configuration -Here is a commented example of configuration +Below you will find commented examples of the following configuration: - server { - listen 443 ssl; - server_name myapp.example.com; +* Authelia portal +* Protected endpoint (Nextcloud) +* Supplementary config - resolver 127.0.0.11 ipv6=off; - set $upstream_verify https://authelia.example.com/api/verify; - set $upstream_endpoint http://nginx-backend; +With the below configuration you can add `authelia.conf` to virtual hosts to support protection with Authelia. +`auth.conf` is utilised to enable the protection either at the root location or a more specific location/route. +`proxy.conf` is included just for completeness. - ssl_certificate /etc/ssl/server.cert; - ssl_certificate_key /etc/ssl/server.key; +#### Supplementary config - # Use HSTS, please beware of what you're doing if you set it. - add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; - add_header X-Frame-Options "SAMEORIGIN"; +##### authelia.conf +```nginx +# Virtual endpoint created by nginx to forward auth requests. +location /authelia { + internal; + set $upstream_authelia http://authelia:9091/api/verify; + proxy_pass_request_body off; + proxy_pass $upstream_authelia; + proxy_set_header Content-Length ""; - location / { - # Send a subsequent request to Authelia to verify if the user is authenticated - # and has the right permissions to access the resource. - auth_request /auth_verify; + # Timeout if the real server is dead + proxy_next_upstream error timeout invalid_header http_500 http_502 http_503; - # Set the X-Forwarded-User and X-Forwarded-Groups with the headers - # returned by Authelia for the backends which can consume them. - # This is not safe, as the backend must make sure that they come from the - # proxy. In the future, it's gonna be safe to just use OAuth. - auth_request_set $user $upstream_http_remote_user; - proxy_set_header X-Forwarded-User $user; + # [REQUIRED] Needed by Authelia to check authorizations of the resource. + # Provide either X-Original-URL and X-Forwarded-Proto or + # X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Uri or both. + # Those headers will be used by Authelia to deduce the target url of the user. + # Basic Proxy Config + client_body_buffer_size 128k; + proxy_set_header Host $host; + proxy_set_header X-Original-URL $scheme://$http_host$request_uri; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $http_host; + proxy_set_header X-Forwarded-Uri $request_uri; + proxy_set_header X-Forwarded-Ssl on; + proxy_redirect http:// $scheme://; + proxy_http_version 1.1; + proxy_set_header Connection ""; + proxy_cache_bypass $cookie_session; + proxy_no_cache $cookie_session; + proxy_buffers 4 32k; - auth_request_set $groups $upstream_http_remote_groups; - proxy_set_header X-Forwarded-Groups $groups; + # Advanced Proxy Config + send_timeout 5m; + proxy_read_timeout 240; + proxy_send_timeout 240; + proxy_connect_timeout 240; +} +``` - # Set the `target_url` variable based on the request. It will be used to build the portal - # URL with the correct redirection parameter. - auth_request_set $target_url $scheme://$http_host$request_uri; - - # If Authelia returns 401, then nginx redirects the user to the login portal. - # If it returns 200, then the request pass through to the backend. - # For other type of errors, nginx will handle them as usual. - error_page 401 =302 https://login.example.com:8080/?rd=$target_url; +##### auth.conf +```nginx +# Basic Authelia Config +# Send a subsequent request to Authelia to verify if the user is authenticated +# and has the right permissions to access the resource. +auth_request /authelia; +# Set the `target_url` variable based on the request. It will be used to build the portal +# URL with the correct redirection parameter. +auth_request_set $target_url $scheme://$http_host$request_uri; +# Set the X-Forwarded-User and X-Forwarded-Groups with the headers +# returned by Authelia for the backends which can consume them. +# This is not safe, as the backend must make sure that they come from the +# proxy. In the future, it's gonna be safe to just use OAuth. +auth_request_set $user $upstream_http_remote_user; +auth_request_set $groups $upstream_http_remote_groups; +proxy_set_header X-Forwarded-User $user; +proxy_set_header X-Forwarded-Groups $groups; +# If Authelia returns 401, then nginx redirects the user to the login portal. +# If it returns 200, then the request pass through to the backend. +# For other type of errors, nginx will handle them as usual. +error_page 401 =302 https://auth.example.com/?rd=$target_url; +``` - proxy_pass $upstream_endpoint; - } +##### proxy.conf +```nginx +client_body_buffer_size 128k; - # Virtual endpoint created by nginx to forward auth requests. - location /auth_verify { - internal; +#Timeout if the real server is dead +proxy_next_upstream error timeout invalid_header http_500 http_502 http_503; - # [OPTIONAL] The IP of the client shown in Authelia logs. - proxy_set_header X-Real-IP $remote_addr; +# Advanced Proxy Config +send_timeout 5m; +proxy_read_timeout 360; +proxy_send_timeout 360; +proxy_connect_timeout 360; - # [REQUIRED] Needed by Authelia to check authorizations of the resource. - # Provide either X-Original-URL and X-Forwarded-Proto or - # X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Uri or both. - # Those headers will be used by Authelia to deduce the target url of the user. - # - # X-Forwarded-Proto is mandatory since Authelia uses the "trust proxy" option. - # See https://expressjs.com/en/guide/behind-proxies.html - proxy_set_header X-Original-URL $scheme://$http_host$request_uri; - - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Forwarded-Host $http_host; - proxy_set_header X-Forwarded-Uri $request_uri; - - # [OPTIONAL] The list of IPs of client and proxies in the chain. - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; +# Basic Proxy Config +proxy_set_header Host $host; +proxy_set_header X-Real-IP $remote_addr; +proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; +proxy_set_header X-Forwarded-Proto $scheme; +proxy_set_header X-Forwarded-Host $http_host; +proxy_set_header X-Forwarded-Uri $request_uri; +proxy_set_header X-Forwarded-Ssl on; +proxy_redirect http:// $scheme://; +proxy_http_version 1.1; +proxy_set_header Connection ""; +proxy_cache_bypass $cookie_session; +proxy_no_cache $cookie_session; +proxy_buffers 64 256k; - proxy_pass_request_body off; - proxy_set_header Content-Length ""; +# If behind reverse proxy, forwards the correct IP +set_real_ip_from 10.0.0.0/8; +set_real_ip_from 172.0.0.0/8; +set_real_ip_from 192.168.0.0/16; +set_real_ip_from fc00::/7; +real_ip_header X-Forwarded-For; +real_ip_recursive on; +``` - proxy_pass $upstream_verify; - } +#### Authelia Portal + +```nginx +server { + server_name auth.example.com; + listen 80; + return 301 https://$server_name$request_uri; +} + +server { + server_name auth.example.com; + listen 443 ssl http2; + include /config/nginx/ssl.conf; + + location / { + set $upstream_authelia http://authelia:9091; # This example assumes a Docker deployment + proxy_pass $upstream_authelia; + include /config/nginx/proxy.conf; # } +} +``` +#### Protected Endpoint + +```nginx +server { + server_name nextcloud.example.com; + listen 80; + return 301 https://$server_name$request_uri; +} + +server { + server_name nextcloud.example.com; + listen 443 ssl http2; + include /config/nginx/ssl.conf; + include /config/nginx/authelia.conf; # Virtual endpoint to forward auth requests + + location / { + set $upstream_nextcloud https://nextcloud; + proxy_pass $upstream_nextcloud; + include /config/nginx/auth.conf; # Activates Authelia for specified route/location, please ensure you have setup the domain in your configuration.yml + include /config/nginx/proxy.conf; # Reverse proxy configuration + } +} +``` [nginx]: https://www.nginx.com/ diff --git a/docs/proxies/traefik1.x.md b/docs/proxies/traefik1.x.md new file mode 100644 index 000000000..41577deec --- /dev/null +++ b/docs/proxies/traefik1.x.md @@ -0,0 +1,90 @@ +# Traefik + +[Traefik 1.x] is a reverse proxy supported by **Authelia**. + +## Configuration + +Below you will find commented examples of the following configuration: + +* Traefik 1.x +* Authelia portal +* Protected endpoint (Nextcloud) + +The below configuration looks to provide examples of running Traefik 1.x with labels to protect your endpoint (Nextcloud in this case). + +Please ensure that you also setup the respective [ACME configuration](https://docs.traefik.io/v1.7/configuration/acme/) for your Traefik setup as this is not covered in the example below. + +##### docker-compose.yml +```yml +version: '3' + +networks: + net: + driver: bridge + +services: + + traefik: + image: traefik:v1.7.20-alpine + container_name: traefik + volumes: + - '/var/run/docker.sock:/var/run/docker.sock' + networks: + - net + labels: + - 'traefik.frontend.rule=Host:traefik.example.com' + - 'traefik.port=8081' + ports: + - 80:80 + - 443:443 + - 8081:8081 + restart: unless-stopped + command: + - '--api' + - '--api.entrypoint=api' + - '--docker' + - '--defaultentrypoints=https' + - '--logLevel=DEBUG' + - '--traefiklog=true' + - '--traefiklog.filepath=/var/log/traefik.log' + - '--entryPoints=Name:http Address::80' + - '--entryPoints=Name:https Address::443 TLS' + - '--entryPoints=Name:api Address::8081' + + authelia: + image: authelia/authelia + container_name: authelia + volumes: + - /path/to/authelia:/var/lib/authelia + - /path/to/authelia/config.yml:/etc/authelia/configuration.yml:ro + networks: + - net + labels: + - 'traefik.frontend.rule=Host:login.example.com' + expose: + - 9091 + restart: unless-stopped + environment: + - TZ=Australia/Melbourne + + nextcloud: + image: linuxserver/nextcloud + container_name: nextcloud + volumes: + - /path/to/nextcloud/config:/config + - /path/to/nextcloud/data:/data + networks: + - net + labels: + - 'traefik.frontend.rule=Host:nextcloud.example.com' + - 'traefik.frontend.auth.forward.address=http://authelia:9091/api/verify?rd=https://login.example.com/' + expose: + - 443 + restart: unless-stopped + environment: + - PUID=1000 + - PGID=1000 + - TZ=Australia/Melbourne +``` + +[Traefik 1.x]: https://docs.traefik.io/v1.7/ diff --git a/docs/proxies/traefik2.x.md b/docs/proxies/traefik2.x.md new file mode 100644 index 000000000..b08f78d68 --- /dev/null +++ b/docs/proxies/traefik2.x.md @@ -0,0 +1,94 @@ +# Traefik2 + +[Traefik 2.x] is a reverse proxy supported by **Authelia**. + +## Configuration + +Below you will find commented examples of the following configuration: + +* Traefik 2.x +* Authelia portal +* Protected endpoint (Nextcloud) + +The below configuration looks to provide examples of running Traefik 2.x with labels to protect your endpoint (Nextcloud in this case). + +Please ensure that you also setup the respective [ACME configuration](https://docs.traefik.io/https/acme/) for your Traefik setup as this is not covered in the example below. + +##### docker-compose.yml +```yml +version: '3' + +networks: + net: + driver: bridge + +services: + + traefik: + image: traefik:v2.1.2 + container_name: traefik + volumes: + - /var/run/docker.sock:/var/run/docker.sock + networks: + - net + labels: + - 'traefik.http.routers.api.rule=Host(`traefik.example.com`)' + - 'traefik.http.routers.api.entrypoints=https' + - 'traefik.http.routers.api.service=api@internal' + - 'traefik.http.routers.api.tls=true' + ports: + - 80:80 + - 443:443 + command: + - '--api' + - '--providers.docker=true' + - '--entrypoints.http=true' + - '--entrypoints.http.address=:80' + - '--entrypoints.https=true' + - '--entrypoints.https.address=:443' + - '--log=true' + - '--log.level=DEBUG' + - '--log.filepath=/var/log/traefik.log' + + authelia: + image: authelia/authelia + container_name: authelia + volumes: + - /path/to/authelia:/var/lib/authelia + - /path/to/authelia/config.yml:/etc/authelia/configuration.yml:ro + networks: + - net + labels: + - 'traefik.http.routers.authelia.rule=Host(`login.example.com`)' + - 'traefik.http.routers.authelia.entrypoints=https' + - 'traefik.http.routers.authelia.tls=true' + expose: + - 9091 + restart: unless-stopped + environment: + - TZ=Australia/Melbourne + + nextcloud: + image: linuxserver/nextcloud + container_name: nextcloud + volumes: + - /path/to/nextcloud/config:/config + - /path/to/nextcloud/data:/data + networks: + - net + labels: + - 'traefik.http.routers.nextcloud.rule=Host(`nextcloud.example.com`)' + - 'traefik.http.routers.nextcloud.entrypoints=https' + - 'traefik.http.routers.nextcloud.tls=true' + - 'traefik.http.routers.nextcloud.middlewares=authelia' + - 'traefik.http.middlewares.authelia.forwardAuth.address=http://authelia:9091/api/verify?rd=https://login.example.com/' + expose: + - 443 + restart: unless-stopped + environment: + - PUID=1000 + - PGID=1000 + - TZ=Australia/Melbourne +``` + +[Traefik 2.x]: https://docs.traefik.io/