Add documentation for nginx proxy.

docs/features.md

@@ -81,6 +81,13 @@ Please check [config.template.yml] to see an example of configuration.
 It is also possible to use [basic authentication] to access a resource 
 protected by a single factor.
 
+Please note that Authelia uses the *Proxy-Authorization* header and not
+*Authorization* since one might be willing to authenticate against both
+Authelia and the proxy. For instance you can use the following command to
+access your service:
+
+    curl -H "Proxy-Authorization: Basic am9objpwYXNzd29yZA==" https://myservice.example.com"
+
 ## Session management with Redis
 
 When your users authenticate against Authelia, sessions are stored in a

docs/proxies/nginx.md

@@ -0,0 +1,75 @@
+# Nginx
+
+[nginx] is the only official reverse proxy supported by **Authelia** for now.
+
+## Configuration
+
+Here is a commented example of configuration
+
+    server {
+        listen 443 ssl;
+        server_name     myapp.example.com;
+
+        resolver 127.0.0.11 ipv6=off;
+        set $upstream_verify https://authelia.example.com/api/verify;
+        set $upstream_endpoint http://nginx-backend;
+
+        ssl_certificate     /etc/ssl/server.crt;
+        ssl_certificate_key /etc/ssl/server.key;
+
+        # 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";
+
+        # Virtual endpoint created by nginx to forward auth requests.
+        location /auth_verify {
+            internal;
+            proxy_set_header            Host $http_host;
+
+            # [REQUIRED] Needed by Authelia to check authorizations of the resource.
+            proxy_set_header            X-Original-URL $scheme://$http_host$request_uri;
+
+            # [OPTIONAL] The IP of the client shown in Authelia logs.
+            proxy_set_header            X-Real-IP $remote_addr;
+
+            # [REQUIRED] Needed by Authelia to ensure that the query was served over SSL
+            #            Check this out: https://expressjs.com/en/guide/behind-proxies.html
+            proxy_set_header            X-Forwarded-Proto $scheme;
+
+            # [OPTIONAL] The list of IPs of client and proxies in the chain.
+            proxy_set_header            X-Forwarded-For $proxy_add_x_forwarded_for;
+
+            proxy_pass_request_body     off;
+            proxy_set_header            Content-Length "";
+
+            proxy_pass                  $upstream_verify;
+        }
+
+        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;
+
+            auth_request_set            $redirect $upstream_http_redirect;
+
+            # 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;
+
+            auth_request_set            $groups $upstream_http_remote_groups;
+            proxy_set_header            Remote-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://login.example.com:8080/#/?rd=$redirect;
+
+            proxy_pass                  $upstream_endpoint;
+        }
+    }
+
+
+[nginx]: https://www.nginx.com/

example/compose/nginx/portal/nginx.conf.ejs

@@ -1,3 +1,8 @@
+#
+# You can find a documented example of configuration in ./docs/proxies/nginx.md.
+#
+
+
 worker_processes  1;
 
 events {