From b311bd5ead75d038f8da72ab9a4fed162c511441 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Michaud?= Date: Sun, 1 Mar 2020 02:11:16 +0100 Subject: [PATCH] [DOCS] Improve documentation about the integration with proxies. (#669) * [DOCS] Improve documentation about the integration with proxies. This improvement resolves #384. * Update index.md --- docs/deployment/supported-proxies/index.md | 44 ++++++++++++++++++++-- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/docs/deployment/supported-proxies/index.md b/docs/deployment/supported-proxies/index.md index e6e93f82..41790709 100644 --- a/docs/deployment/supported-proxies/index.md +++ b/docs/deployment/supported-proxies/index.md @@ -1,12 +1,48 @@ --- layout: default -title: Supported Proxies +title: Proxy Integration parent: Deployment nav_order: 4 has_children: true --- -# Supported Proxies +# Integration with proxies -**Authelia** works in collaboration with reverse proxies. Here you can find -the documentation of the configuration required for every supported proxies. \ No newline at end of file +**Authelia** works in collaboration with reverse proxies. In the sub-pages you +can find the documentation of the configuration required for every supported +proxy. + +If you are not aware of the workflow of an authentication request, reading this +[documentation](./home/architecture) first is highly recommended. + + +## How Authelia integrates with proxies? + +Authelia takes authentication requests coming from the proxy and targeting the +`/api/verify` endpoint exposed by Authelia. Two pieces of information are required for +Authelia to be able to authenticate the user request: + +* The session cookie or a `Proxy-Authorization` header (see [single factor authentication](./features/single-factor)). +* The target URL of the user request (used primarily for [access control](./features/access-control)). + +The target URL can be provided using one of the following ways: + +* With `X-Original-URL` header containing the complete URL of the initial request. +* With a combination of `X-Forwarded-Proto`, `X-Forwarded-Host` and `X-Forwarded-URI` headers. + +In the case of Traefik, those headers are automatically provided and therefore don't +appear in the configuration examples. + +## Redirection to the login portal + +The endpoint `/api/verify` has different behaviors depending on whether +the `rd` (for redirection) query parameter is provided. + +If redirection parameter is provided and contains the URL to the login portal +served by Authelia, the request will either generate a 200 response +if the request is authenticated or perform a redirection (302 response) to the +login portal if not authenticated yet. + +If no redirection parameter is provided, the response code is either 200 or 401. The +redirection must then be handled by the proxy when an error is detected +(see [nginx](./deployment/supported-proxies/nginx) example).