From 3822286c3beb862c9366d9406ed8007a86b37b6f Mon Sep 17 00:00:00 2001 From: James Elliott Date: Sun, 2 Oct 2022 13:59:09 +1100 Subject: [PATCH] docs: add envoy docs (#3789) Adds and adjusts documentation for Envoy. --- README.md | 8 +- .../en/integration/kubernetes/istio.md | 90 ++++++++ .../integration/kubernetes/nginx-ingress.md | 2 +- docs/content/en/integration/proxies/caddy.md | 1 + docs/content/en/integration/proxies/envoy.md | 210 +++++++++++++++++- .../content/en/integration/proxies/support.md | 30 +-- .../en/overview/prologue/supported-proxies.md | 34 +-- 7 files changed, 326 insertions(+), 49 deletions(-) create mode 100644 docs/content/en/integration/kubernetes/istio.md diff --git a/README.md b/README.md index ada435e5e..cdd3264ee 100644 --- a/README.md +++ b/README.md @@ -93,17 +93,11 @@ Docker or on top of [Kubernetes]. +

-***Help Wanted:*** Assistance would be appreciated in getting Authelia working with -[Envoy](https://www.envoyproxy.io/). - -

- -

- ## Getting Started See the [Get Started Guide](https://www.authelia.com/integration/prologue/get-started/) or one of the curated examples diff --git a/docs/content/en/integration/kubernetes/istio.md b/docs/content/en/integration/kubernetes/istio.md new file mode 100644 index 000000000..29e14a43f --- /dev/null +++ b/docs/content/en/integration/kubernetes/istio.md @@ -0,0 +1,90 @@ +--- +title: "Istio" +description: "A guide to integrating Authelia with the Istio Kubernetes Ingress." +lead: "A guide to integrating Authelia with the Istio Kubernetes Ingress." +date: 2022-06-15T17:51:47+10:00 +draft: false +images: [] +menu: +integration: +parent: "kubernetes" +weight: 551 +toc: true +--- + +Istio uses [Envoy](../proxies/envoy.md) as an Ingress. This means it has a relatively comprehensive integration option. + +## Example + +This example assumes that you have deployed an Authelia pod and you have configured it to be served on the URL +`https://auth.example.com` and there is a Kubernetes Service with the name `authelia` in the `default` namespace with +TCP port `80` configured to route to the Authelia pod's HTTP port and that your cluster is configured with the default +DNS domain name of `cluster.local`. + +### Operator + +This is an example IstioOperator manifest adjusted to authenticate with Authelia. This example only shows the necessary +portions of the resource that you add as well as context. You will need to adapt it to your needs. + +```yaml +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +spec: + meshConfig: + extensionProviders: + - name: 'authelia' + envoyExtAuthzHttp: + service: 'authelia.default.svc.cluster.local' + port: 80 + pathPrefix: '/api/verify/' + includeRequestHeadersInCheck: + - accept + - cookie + - proxy-authorization + headersToUpstreamOnAllow: + - 'authorization' + - 'proxy-authorization' + - 'remote-*' + - 'authelia-*' + includeAdditionalHeadersInCheck: + X-Authelia-URL: 'https://auth.example.com/' + X-Forwarded-Method: '%REQ(:METHOD)%' + X-Forwarded-Proto: '%REQ(:SCHEME)%' + X-Forwarded-Host: '%REQ(:AUTHORITY)%' + X-Forwarded-URI: '%REQ(:PATH)%' + X-Forwarded-For: '%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%' + headersToDownstreamOnDeny: + - set-cookie + headersToDownstreamOnAllow: + - set-cookie +``` + +### Authorization Policy + +The following [Authorization Policy] applies the above filter extension provider to the `nextcloud.example.com` domain: + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: nextcloud + namespace: apps +spec: + action: CUSTOM + provider: + name: 'authelia' + rules: + - to: + - operation: + hosts: + - 'nextcloud.example.com' +``` + +## See Also + +- Istio [External Authentication](https://istio.io/latest/docs/tasks/security/authorization/authz-custom/) Documentation +- Istio [Authorization Policy] Documentation +- Istio [IstioOperator Options](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/) Documentation +- Istio [MeshConfig Extension Provider EnvoyExtAuthz HTTP Provider](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig-ExtensionProvider-EnvoyExternalAuthorizationHttpProvider) Documentation + +[Authorization Policy]: https://istio.io/latest/docs/reference/config/security/authorization-policy/ diff --git a/docs/content/en/integration/kubernetes/nginx-ingress.md b/docs/content/en/integration/kubernetes/nginx-ingress.md index c50f74f0d..614626e60 100644 --- a/docs/content/en/integration/kubernetes/nginx-ingress.md +++ b/docs/content/en/integration/kubernetes/nginx-ingress.md @@ -8,7 +8,7 @@ images: [] menu: integration: parent: "kubernetes" -weight: 551 +weight: 552 toc: true --- diff --git a/docs/content/en/integration/proxies/caddy.md b/docs/content/en/integration/proxies/caddy.md index 55b2e502a..904fb17df 100644 --- a/docs/content/en/integration/proxies/caddy.md +++ b/docs/content/en/integration/proxies/caddy.md @@ -151,6 +151,7 @@ example.com { } ``` {{< /details >}} + ### Advanced example The advanced example allows for more flexible customization, however the [basic example](#basic-examples) should be diff --git a/docs/content/en/integration/proxies/envoy.md b/docs/content/en/integration/proxies/envoy.md index 342ec0c14..b887dc1ea 100644 --- a/docs/content/en/integration/proxies/envoy.md +++ b/docs/content/en/integration/proxies/envoy.md @@ -14,20 +14,13 @@ aliases: - /i/envoy --- -[Envoy] is probably supported by __Authelia__. +[Envoy] is supported by __Authelia__. *__Important:__ When using these guides it's important to recognize that we cannot provide a guide for every possible method of deploying a proxy. These guides show a suggested setup only and you need to understand the proxy configuration and customize it to your needs. To-that-end we include links to the official proxy documentation throughout this documentation and in the [See Also](#see-also) section.* -## UNDER CONSTRUCTION - -It's currently not certain, but fairly likely that [Envoy] is supported by __Authelia__. We wish to add documentation -and thus if anyone has this working please let us know. - -We will aim to perform documentation for this on our own but there is no current timeframe. - ## Get Started It's __*strongly recommended*__ that users setting up *Authelia* for the first time take a look at our @@ -44,11 +37,210 @@ how you can configure multiple IP ranges. You should customize this example to f You should only include the specific IP address ranges of the trusted proxies within your architecture and should not trust entire subnets unless that subnet only has trusted proxies and no other services.* -## Potential +## Configuration + +Below you will find commented examples of the following configuration: + +* Authelia Portal +* Protected Endpoint (Nextcloud) + +### Theoretical Example Support for [Envoy] should be possible via [Envoy]'s [external authorization](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-extauthz). +{{< details "docker-compose.yaml" >}} +```yaml +--- +version: "3.8" +networks: + net: + driver: bridge +services: + envoy: + container_name: envoy + image: envoyproxy/envoy:v1.23.0 + restart: unless-stopped + networks: + net: {} + ports: + - '80:8080' + - '443:8443' + volumes: + - ${PWD}/data/envoy/envoy.yaml:/etc/envoy/envoy.yaml:ro + - ${PWD}/data/certificates:/certificates:ro + authelia: + container_name: authelia + image: authelia/authelia + restart: unless-stopped + networks: + net: {} + expose: + - 9091 + volumes: + - ${PWD}/data/authelia/config:/config + environment: + TZ: "Australia/Melbourne" + nextcloud: + container_name: nextcloud + image: linuxserver/nextcloud + restart: unless-stopped + networks: + net: {} + expose: + - 443 + volumes: + - ${PWD}/data/nextcloud/config:/config + - ${PWD}/data/nextcloud/data:/data + environment: + PUID: "1000" + PGID: "1000" + TZ: "Australia/Melbourne" +``` +{{< /details >}} + +{{< details "envoy.yaml" >}} +```yaml +static_resources: + listeners: + - name: listener_http + address: + socket_address: + address: 0.0.0.0 + port_value: 8080 + filter_chains: + - filters: + - name: envoy.filters.network.http_connection_manager + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager + codec_type: auto + stat_prefix: ingress_http + route_config: + name: local_route + virtual_hosts: + - name: backend + domains: ["*"] + routes: + - match: + prefix: "/" + redirect: + https_redirect: true + http_filters: + - name: envoy.filters.http.router + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router + - name: listener_https + address: + socket_address: + address: 0.0.0.0 + port_value: 8443 + filter_chains: + - filters: + - name: envoy.filters.network.http_connection_manager + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager + stat_prefix: ingress_http + use_remote_address: true + skip_xff_append: false + route_config: + name: local_route + virtual_hosts: + - name: whoami_service + domains: ["nextcloud.example.com"] + routes: + - match: + prefix: "/" + route: + cluster: nextcloud + - name: authelia_service + domains: ["auth.example.com"] + typed_per_filter_config: + envoy.filters.http.ext_authz: + "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute + disabled: true + routes: + - match: + prefix: "/" + route: + cluster: authelia + http_filters: + - name: envoy.filters.http.ext_authz + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz + http_service: + path_prefix: '/api/verify/' + server_uri: + uri: authelia:9091 + cluster: authelia + timeout: 0.25s + authorization_request: + allowed_headers: + patterns: + - exact: accept + - exact: cookie + - exact: proxy-authorization + headers_to_add: + - key: X-Authelia-URL + value: 'https://auth.example.com/' + - key: X-Forwarded-Method + value: '%REQ(:METHOD)%' + - key: X-Forwarded-Proto + value: '%REQ(:SCHEME)%' + - key: X-Forwarded-Host + value: '%REQ(:AUTHORITY)%' + - key: X-Forwarded-Uri + value: '%REQ(:PATH)%' + - key: X-Forwarded-For + value: '%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%' + authorization_response: + allowed_upstream_headers: + patterns: + - exact: authorization + - exact: proxy-authorization + - prefix: remote- + - prefix: authelia- + allowed_client_headers: + patterns: + - exact: set-cookie + allowed_client_headers_on_success: + patterns: + - exact: set-cookie + failure_mode_allow: false + - name: envoy.filters.http.router + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router + clusters: + - name: nextcloud + connect_timeout: 0.25s + type: LOGICAL_DNS + dns_lookup_family: V4_ONLY + lb_policy: ROUND_ROBIN + load_assignment: + cluster_name: nextcloud + endpoints: + - lb_endpoints: + - endpoint: + address: + socket_address: + address: nextcloud + port_value: 80 + - name: authelia + connect_timeout: 0.25s + type: LOGICAL_DNS + dns_lookup_family: V4_ONLY + lb_policy: ROUND_ROBIN + load_assignment: + cluster_name: authelia + endpoints: + - lb_endpoints: + - endpoint: + address: + socket_address: + address: authelia + port_value: 9091 +``` +{{< /details >}} + ## See Also * [Envoy External Authorization Documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-extauthz) diff --git a/docs/content/en/integration/proxies/support.md b/docs/content/en/integration/proxies/support.md index ac47789a6..a378f8871 100644 --- a/docs/content/en/integration/proxies/support.md +++ b/docs/content/en/integration/proxies/support.md @@ -15,19 +15,19 @@ aliases: - /docs/home/supported-proxies.html --- -| Proxy | [Standard](#standard) | [Kubernetes](#kubernetes) | [XHR Redirect](#xhr-redirect) | [Request Method](#request-method) | -|:---------------------:|:----------------------------------------------------------------:|:------------------------------------------------------------------------------------:|:------------------------------------:|:------------------------------------:| -| [Traefik] | [](traefik.md) | [](../../integration/kubernetes/traefik-ingress.md) | | | -| [NGINX] | [](nginx.md) | [](../../integration/kubernetes/nginx-ingress.md) | | | -| [NGINX Proxy Manager] | [](nginx-proxy-manager.md) | | | | -| [SWAG] | [](swag.md) | | | | -| [HAProxy] | [](haproxy.md) | | | | -| [Caddy] | [](caddy.md) | | | | -| [Traefik] 1.x | [](traefikv1.md) | | | | -| [Envoy] | [](envoy.md) | | | | -| [Skipper] | [](skipper.md) | | | | -| [Apache] | [](#apache) | | | | -| [IIS] | [](#iis) | | | | +| Proxy | [Standard](#standard) | [Kubernetes](#kubernetes) | [XHR Redirect](#xhr-redirect) | [Request Method](#request-method) | +|:---------------------:|:----------------------------------------------------------------:|:------------------------------------------------------------------------------------:|:-----------------------------------------------------:|:-----------------------------------------------------:| +| [Traefik] | [](traefik.md) | [](../../integration/kubernetes/traefik-ingress.md) | | | +| [NGINX] | [](nginx.md) | [](../../integration/kubernetes/nginx-ingress.md) | | | +| [NGINX Proxy Manager] | [](nginx-proxy-manager.md) | | | | +| [SWAG] | [](swag.md) | | | | +| [HAProxy] | [](haproxy.md) | | | | +| [Caddy] | [](caddy.md) | | | | +| [Traefik] 1.x | [](traefikv1.md) | | | | +| [Envoy] | [](envoy.md) | [](../../integration/kubernetes/istio.md) | | | +| [Skipper] | [](skipper.md) | | | | +| [Apache] | [](#apache) | | | | +| [IIS] | [](#iis) | | | | Legend: @@ -87,8 +87,8 @@ available in [Kubernetes]. You would likely have to build your own [HAProxy] ima ### Envoy -[Envoy] is currently not documented, however a small pending feature will add complete support for [Envoy]. This is -possible via [Envoy]'s [external authorization](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-extauthz). +[Envoy] is currently only partially documented however it is technically supported via [Envoy]'s +[external authorization](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-extauthz). ### Caddy diff --git a/docs/content/en/overview/prologue/supported-proxies.md b/docs/content/en/overview/prologue/supported-proxies.md index 3aa9de3e1..01a12fcc5 100644 --- a/docs/content/en/overview/prologue/supported-proxies.md +++ b/docs/content/en/overview/prologue/supported-proxies.md @@ -14,28 +14,28 @@ toc: false The following table is a support matrix for Authelia features and specific reverse proxies. -| Proxy | Standard | Kubernetes | XHR Redirect | Request Method | -|:---------------------:|:-------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------:|:------------------------------------:|:------------------------------------:| -| [Traefik] | [](../../integration/proxies/traefik.md) | [](../../integration/kubernetes/traefik-ingress.md) | | | -| [NGINX] | [](../../integration/proxies/nginx.md) | [](../../integration/kubernetes/nginx-ingress.md) | | | -| [NGINX Proxy Manager] | [](../../integration/proxies/nginx-proxy-manager.md) | | | | -| [SWAG] | [](../../integration/proxies/swag.md) | | | | -| [HAProxy] | [](../../integration/proxies/haproxy.md) | | | | -| [Caddy] | [](../../integration/proxies/caddy.md) | | | | -| [Traefik] 1.x | [](../../integration/proxies/traefikv1.md) | | | | -| [Envoy] | [](../../integration/proxies/envoy.md) | | | | -| [Skipper] | [](../../integration/proxies/skipper.md) | | | | -| [Apache] | | | | | -| [IIS] | | | | | +| Proxy | [Standard](#standard) | [Kubernetes](#kubernetes) | [XHR Redirect](#xhr-redirect) | [Request Method](#request-method) | +|:---------------------:|:-------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------:|:-----------------------------------------------------:|:-----------------------------------------------------:| +| [Traefik] | [](../../integration/proxies/traefik.md) | [](../../integration/kubernetes/traefik-ingress.md) | | | +| [NGINX] | [](../../integration/proxies/nginx.md) | [](../../integration/kubernetes/nginx-ingress.md) | | | +| [NGINX Proxy Manager] | [](../../integration/proxies/nginx-proxy-manager.md) | | | | +| [SWAG] | [](../../integration/proxies/swag.md) | | | | +| [HAProxy] | [](../../integration/proxies/haproxy.md) | | | | +| [Caddy] | [](../../integration/proxies/caddy.md) | | | | +| [Traefik] 1.x | [](../../integration/proxies/traefikv1.md) | | | | +| [Envoy] | [](../../integration/proxies/envoy.md) | [](../../integration/kubernetes/istio.md) | | | +| [Skipper] | [](../../integration/proxies/skipper.md) | | | | +| [Apache] | | | | | +| [IIS] | | | | | Legend: -| Icon | Meaning | -|:------------------------------------:|:-------------------:| -| | Supported | +| Icon | Meaning | +|-------------------------------------:|:-------------------:| +| | Supported | | | Unknown | | | Partially Supported | -| | Not Supported | +| | Not Supported | ## More Information