RPJosh
/
authelia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update proxy docs (#4449)

pull/4450/head
James Elliott 2022-11-30 09:12:50 +11:00 committed by GitHub
parent 85a579ca5a
commit 442cb272d9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 176 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/content/en/integration/proxies/nginx.md
View File

@ -387,6 +387,7 @@ location /authelia {
## Headers
## The headers starting with X-* are required.
proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
proxy_set_header X-Original-Method $request_method;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $http_host;
@ -470,6 +471,7 @@ location /authelia-basic {
## Headers
## The headers starting with X-* are required.
proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
proxy_set_header X-Original-Method $request_method;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $http_host;

34
docs/content/en/integration/proxies/support.md
View File

@ -16,27 +16,27 @@ aliases:
---
| Proxy | [Standard](#standard) | [Kubernetes](#kubernetes) | [XHR Redirect](#xhr-redirect) | [Request Method](#request-method) |
|:---------------------:|:----------------------------------------------------------------:|:------------------------------------------------------------------------------------:|:-----------------------------------------------------:|:-----------------------------------------------------:|
| [Traefik] | [<i class="icon-support-full"></i>](traefik.md) | [<i class="icon-support-full"></i>](../../integration/kubernetes/traefik-ingress.md) | <i class="icon-support-full"></i> | <i class="icon-support-full"></i> |
| [NGINX] | [<i class="icon-support-full"></i>](nginx.md) | [<i class="icon-support-full"></i>](../../integration/kubernetes/nginx-ingress.md) | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-full"></i> |
| [NGINX Proxy Manager] | [<i class="icon-support-full"></i>](nginx-proxy-manager.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-full"></i> |
| [SWAG] | [<i class="icon-support-full"></i>](swag.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-full"></i> |
| [HAProxy] | [<i class="icon-support-full"></i>](haproxy.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-unknown"></i> | <i class="icon-support-full"></i> |
| [Caddy] | [<i class="icon-support-full"></i>](caddy.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-full"></i> | <i class="icon-support-full"></i> |
| [Traefik] 1.x | [<i class="icon-support-full"></i>](traefikv1.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-full"></i> | <i class="icon-support-full"></i> |
| [Envoy] | [<i class="icon-support-full"></i>](envoy.md) | [<i class="icon-support-full"></i>](../../integration/kubernetes/istio.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-full"></i> |
| [Skipper] | [<i class="icon-support-full"></i>](skipper.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-unknown"></i> | <i class="icon-support-unknown"></i> |
| [Apache] | [<i class="icon-support-none" alt="Not Supported"></i>](#apache) | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> |
| [IIS] | [<i class="icon-support-none" alt="Not Supported"></i>](#iis) | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> |
|:---------------------:|:------------------------------------------------------------------:|:-------------------------------------------------------------------------------------:|:---------------------------------:|:---------------------------------:|
| [Traefik] | {{% support support="full" link="traefik.md" %}} | {{% support support="full" link="../../integration/kubernetes/traefik-ingress.md" %}} | {{% support support="full" %}} | {{% support support="full" %}} |
| [Caddy] | {{% support support="full" link="caddy.md" %}} | {{% support support="unknown" %}} | {{% support support="full" %}} | {{% support support="full" %}} |
| [Envoy] | {{% support support="full" link="envoy.md" %}} | {{% support support="full" link="../../integration/kubernetes/istio.md" %}} | {{% support support="unknown" %}} | {{% support support="full" %}} |
| [NGINX] | {{% support support="full" link="nginx.md" %}} | {{% support support="full" link="../../integration/kubernetes/nginx-ingress.md" %}} | {{% support %}} | {{% support support="full" %}} |
| [NGINX Proxy Manager] | {{% support support="full" link="nginx-proxy-manager/index.md" %}} | {{% support support="unknown" %}} | {{% support %}} | {{% support support="full" %}} |
| [SWAG] | {{% support support="full" link="swag.md" %}} | {{% support support="unknown" %}} | {{% support %}} | {{% support support="full" %}} |
| [HAProxy] | {{% support support="full" link="haproxy.md" %}} | {{% support support="unknown" %}} | {{% support support="unknown" %}} | {{% support support="full" %}} |
| [Skipper] | {{% support support="full" link="skipper.md" %}} | {{% support support="unknown" %}} | {{% support support="unknown" %}} | {{% support support="unknown" %}} |
| [Traefik] 1.x | {{% support support="full" link="traefikv1.md" %}} | {{% support support="unknown" %}} | {{% support support="full" %}} | {{% support support="full" %}} |
| [Apache] | {{% support link="#apache" %}} | {{% support %}} | {{% support %}} | {{% support %}} |
| [IIS] | {{% support link="#iis" %}} | {{% support %}} | {{% support %}} | {{% support %}} |
Legend:
| Icon | Meaning |
|:------------------------------------:|:-------------------:|
| <i class="icon-support-full"></i> | Supported |
| <i class="icon-support-unknown"></i> | Unknown |
| <i class="icon-support-partial"></i> | Partially Supported |
| <i class="icon-support-none"></i> | Not Supported |
|:---------------------------------:|:-------------------:|
| {{% support support="full" %}} | Supported |
| {{% support support="unknown" %}} | Unknown |
| {{% support support="partial" %}} | Partially Supported |
| {{% support support="none" %}} | Not Supported |
## Support

165
docs/content/en/integration/proxies/swag.md
View File

@ -49,9 +49,15 @@ One current caveat of the [SWAG] implementation is that it serves Authelia as a
This is partly because Webauthn requires that the domain is an exact match when registering and authenticating and it is
possible that due to web standards this will never change.
In addition this represents a bad user experience in some instances as users sometimes visit the
`https://app.example.com/auth` URL which doesn't automatically redirect the user to `https://app.example.com` (if they
visit `https://app.example.com` then they'll be redirected to authenticate then redirected back to their original URL).
In addition this represents a bad user experience in some instances such as:
- Users sometimes visit the `https://app.example.com/authelia` URL which doesn't automatically redirect the user to
`https://app.example.com` (if they visit `https://app.example.com` then they'll be redirected to authenticate then
redirected back to their original URL).
- Administrators may wish to setup OpenID Connect 1.0 in which case it also doesn't represent a good user experience.
Taking these factors into consideration we're adapting our [SWAG] guide to use what we consider best for the users and
most easily supported. Users who wish to use the [SWAG] guide are free to do so but may not receive the same support.
## Trusted Proxies
@ -61,22 +67,116 @@ Especially if you have never read it before.*
To configure trusted proxies for [SWAG] see the [NGINX] section on [Trusted Proxies](nginx.md#trusted-proxies).
Adapting this to [SWAG] is beyond the scope of this documentation.
## 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:
swag:
container_name: swag
image: lscr.io/linuxserver/swag
restart: unless-stopped
networks:
net:
aliases: []
ports:
- '80:80'
- '443:443'
volumes:
- ${PWD}/data/swag:/config
environment:
PUID: '1000'
PGID: '1000'
TZ: 'Australia/Melbourne'
URL: 'example.com'
SUBDOMAINS: 'www,whoami,auth,nextcloud,'
VALIDATION: 'http'
CERTPROVIDER: 'cloudflare'
ONLY_SUBDOMAINS: 'false'
STAGING: 'true'
cap_add:
- NET_ADMIN
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 >}}
## Prerequisite Steps
These steps must be followed regardless of the choice of [subdomain](#subdomain-steps) or [subpath](#subpath-steps).
In the [SWAG] `/config` mount which is mounted to `${PWD}/data/swag` in our example:
1. Deploy __Authelia__ to your docker network with the `container_name` of `authelia` and ensure it's listening on the
default port and you have not configured the __Authelia__ server TLS settings.
1. Create a folder named `snippets/authelia`:
- The `mkdir -p ${PWD}/data/swag/snippets/authelia` command should achieve this on Linux.
2. Create the `${PWD}/data/swag/nginxsnippets/authelia/location.conf` file which can be found [here](nginx.md#authelia-locationconf).
3. Create the `${PWD}/data/swag/nginxsnippets/authelia/authrequest.conf` file which can be found [here](nginx.md#authelia-authrequestconf).
- Ensure you adjust the line `error_page 401 =302 https://auth.example.com/?rd=$target_url;` replacing `https://auth.example.com/` with your external Authelia URL.
## Subdomain Steps
## Protected Application
In the server configuration for the application you want to protect:
1. Edit the `/config/nginx/proxy-confs/` file for the application you wish to protect.
2. Uncomment the `#include /config/nginx/authelia-server.conf;` line which should be within the `server` block
but not inside any `location` blocks.
3. Uncomment the `#include /config/nginx/authelia-location.conf;` line which should be within the applications
`location` block.
2. Under the `#include /config/nginx/authelia-server.conf;` line which should be within the `server` block
but not inside any `location` blocks add the following line: ``.
3. Under the `#include /config/nginx/authelia-location.conf;` line which should be within the applications
`location` block add the following line `include /config/nginx/snippets/authelia/authrequest.conf;`.
### Example
@ -85,55 +185,28 @@ server {
listen 443 ssl;
listen [::]:443 ssl;
server_name heimdall.*;
server_name whoami.*;
include /config/nginx/ssl.conf;
client_max_body_size 0;
# Authelia: Step 1.
include /config/nginx/authelia-server.conf;
#include /config/nginx/authelia-server.conf;
include /config/nginx/snippets/authelia/location.conf;
location / {
# Authelia: Step 2.
include /config/nginx/authelia-location.conf;
#include /config/nginx/authelia-location.conf;
include /config/nginx/snippets/authelia/authrequest.conf;
include /config/nginx/proxy.conf;
resolver 127.0.0.11 valid=30s;
set $upstream_app heimdall;
set $upstream_port 443;
set $upstream_proto https;
proxy_pass $upstream_proto://$upstream_app:$upstream_port;
}
}
```
## Subpath Steps
*__Note:__ Steps 1 and 2 only need to be done once, even if you wish to protect multiple applications.*
1. Edit `/config/nginx/proxy-confs/default`.
2. Uncomment the `#include /config/nginx/authelia-server.conf;` line.
3. Edit the `/config/nginx/proxy-confs/` file for the application you wish to protect.
4. Uncomment the `#include /config/nginx/authelia-location.conf;` line which should be within the applications
`location` block.
### Example
```nginx
location ^~ /bazarr/ {
# Authelia: Step 4.
include /config/nginx/authelia-location.conf;
include /config/nginx/proxy.conf;
resolver 127.0.0.11 valid=30s;
set $upstream_app bazarr;
set $upstream_port 6767;
set $upstream_app whoami;
set $upstream_port 80;
set $upstream_proto http;
proxy_pass $upstream_proto://$upstream_app:$upstream_port;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
}
}
```

36
docs/content/en/overview/prologue/supported-proxies.md
View File

@ -14,28 +14,28 @@ toc: false
The following table is a support matrix for Authelia features and specific reverse proxies.
| Proxy | [Standard](#standard) | [Kubernetes](#kubernetes) | [XHR Redirect](#xhr-redirect) | [Request Method](#request-method) |
|:---------------------:|:-------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------:|:-----------------------------------------------------:|:-----------------------------------------------------:|
| [Traefik] | [<i class="icon-support-full"></i>](../../integration/proxies/traefik.md) | [<i class="icon-support-full"></i>](../../integration/kubernetes/traefik-ingress.md) | <i class="icon-support-full"></i> | <i class="icon-support-full"></i> |
| [NGINX] | [<i class="icon-support-full"></i>](../../integration/proxies/nginx.md) | [<i class="icon-support-full"></i>](../../integration/kubernetes/nginx-ingress.md) | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-full"></i> |
| [NGINX Proxy Manager] | [<i class="icon-support-full"></i>](../../integration/proxies/nginx-proxy-manager.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-full"></i> |
| [SWAG] | [<i class="icon-support-full"></i>](../../integration/proxies/swag.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-full"></i> |
| [HAProxy] | [<i class="icon-support-full"></i>](../../integration/proxies/haproxy.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-unknown"></i> | <i class="icon-support-full"></i> |
| [Caddy] | [<i class="icon-support-full"></i>](../../integration/proxies/caddy.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-full"></i> | <i class="icon-support-full"></i> |
| [Traefik] 1.x | [<i class="icon-support-full"></i>](../../integration/proxies/traefikv1.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-full"></i> | <i class="icon-support-full"></i> |
| [Envoy] | [<i class="icon-support-full"></i>](../../integration/proxies/envoy.md) | [<i class="icon-support-full"></i>](../../integration/kubernetes/istio.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-full"></i> |
| [Skipper] | [<i class="icon-support-full"></i>](../../integration/proxies/skipper.md) | <i class="icon-support-unknown"></i> | <i class="icon-support-unknown"></i> | <i class="icon-support-unknown"></i> |
| [Apache] | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> |
| [IIS] | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> | <i class="icon-support-none" alt="Not Supported"></i> |
| Proxy | Standard | Kubernetes | XHR Redirect | Request Method |
|:---------------------:|:--------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------:|:---------------------------------:|:---------------------------------:|
| [Traefik] | {{% support support="full" link="../../integration/proxies/traefik.md" %}} | {{% support support="full" link="../../integration/kubernetes/traefik-ingress.md" %}} | {{% support support="full" %}} | {{% support support="full" %}} |
| [Caddy] | {{% support support="full" link="../../integration/proxies/caddy.md" %}} | {{% support support="unknown" %}} | {{% support support="full" %}} | {{% support support="full" %}} |
| [Envoy] | {{% support support="full" link="../../integration/proxies/envoy.md" %}} | {{% support support="full" link="../../integration/kubernetes/istio.md" %}} | {{% support support="unknown" %}} | {{% support support="full" %}} |
| [NGINX] | {{% support support="full" link="../../integration/proxies/nginx.md" %}} | {{% support support="full" link="../../integration/kubernetes/nginx-ingress.md" %}} | {{% support %}} | {{% support support="full" %}} |
| [NGINX Proxy Manager] | {{% support support="full" link="../../integration/proxies/nginx-proxy-manager/index.md" %}} | {{% support %}} | {{% support %}} | {{% support support="full" %}} |
| [SWAG] | {{% support support="full" link="../../integration/proxies/swag.md" %}} | {{% support %}} | {{% support %}} | {{% support support="full" %}} |
| [HAProxy] | {{% support support="full" link="../../integration/proxies/haproxy.md" %}} | {{% support support="unknown" %}} | {{% support support="unknown" %}} | {{% support support="full" %}} |
| [Traefik] 1.x | {{% support support="full" link="../../integration/proxies/traefikv1.md" %}} | {{% support support="unknown" %}} | {{% support support="full" %}} | {{% support support="full" %}} |
| [Skipper] | {{% support support="full" link="../../integration/proxies/skipper.md" %}} | {{% support %}} | {{% support support="unknown" %}} | {{% support support="unknown" %}} |
| [Apache] | {{% support %}} | {{% support %}} | {{% support %}} | {{% support %}} |
| [IIS] | {{% support %}} | {{% support %}} | {{% support %}} | {{% support %}} |
Legend:
| Icon | Meaning |
|-------------------------------------:|:-------------------:|
| <i class="icon-support-full"></i> | Supported |
| <i class="icon-support-unknown"></i> | Unknown |
| <i class="icon-support-partial"></i> | Partially Supported |
| <i class="icon-support-none"></i> | Not Supported |
|:----------------------------------:|:-------------------:|
| {{% support support="full" %}} | Supported |
| {{% support support="unknown" %}} | Unknown |
| {{% support support="partial" %}} | Partially Supported |
| {{% support %}} | Not Supported |
## More Information

9
docs/content/en/roadmap/active/openid-connect.md
View File

@ -113,6 +113,13 @@ Feature List:
### Beta 6
{{< roadmap-status stage="in-progress" version="v4.38.0" >}}
* [OAuth 2.0 Pushed Authorization Requests](https://www.rfc-editor.org/rfc/rfc9126.html)
### Beta 7
{{< roadmap-status >}}
Feature List:
@ -122,7 +129,7 @@ Feature List:
See [OpenID Connect Core (Mandatory to Implement Features for All OpenID Providers)].
### Beta 7
### Beta 8
{{< roadmap-status >}}

9
docs/layouts/shortcodes/support.html 100644
View File

@ -0,0 +1,9 @@
{{- $class := "icon-support-none" }}{{ $title := "Not Supported" }}
{{- with .Get "support" }}
{{- if (eq . "full") }}{{ $class = "icon-support-full" }}{{ $title = "Fully Supported" }}
{{- else if (eq . "partial") }}{{ $class = "icon-support-partial" }}{{ $title = "Partially Supported" }}
{{- else if (eq . "unknown") }}{{ $class = "icon-support-unknown" }}{{ $title = "Unknown" }}
{{- end }}{{ end }}
{{- with .Get "title" }}{{ $title = . }}{{ end }}
{{- with .Get "link" }}[<i class="{{ $class }}" data-toggle="tooltip" data-placement="top" title="{{ $title }}"></i>]({{ . }})
{{- else }}<i class="{{ $class }}" data-toggle="tooltip" data-placement="top" title="{{ $title }}"></i>{{ end }}