Proxies

Authelia works in collaboration with several reverse proxies. In this section you will find the documentation of the various tested proxies with examples of how you may configure them. We are eager for users to help us provide better examples of already documented proxies, as well as provide us examples of undocumented proxies.

Get started#

It’s strongly recommended that users setting up Authelia for the first time take a look at our Get started guide. This takes you through various steps which are essential to bootstrapping Authelia.

Support#

See support for support information.

Required Headers#

There are several required headers for Authelia to operate properly. These headers are considered part of the supported configuration and they are assumed to be present for future development.

You may not be able to do several things that rely on these headers such as but not limited to:

• Properly identify the request information for Access Control, such as client IP, hostname, request URL or Scheme, etc.
• Properly identify the correct domain for session cookies.
• Properly identify the public facing URL for redirection or email links making redirection or email based verifications inoperable.
• Properly identify the OpenID Connect 1.0 Issuer or Endpoint URL’s making OpenID Connect 1.0 inoperable.
• Properly identify the WebAuthn Relying Party Identifier making WebAuthn inoperable.

In addition to the Proxy Authorization Endpoint implementations and the headers required by those, Authelia itself requires the following headers are set when secured behind a reverse proxy i.e. the headers a reverse proxy must include for the Authelia portal app itself:

• Scheme Detection:
  • Default: X-Forwarded-Proto (header)
  • Fallback: TLS (listening socket state)
• Host Detection:
  • Default: X-Forwarded-Host (header)
  • Fallback: Host (header)
• Path Detection:
  • Default: X-Forwarded-URI (header)
  • Fallback: Start Line Request Target (start line)
• Remote IP:
  • Default: X-Forwarded-For
  • Fallback: TCP source IP

Important Notes#

• When configuring Authelia on a subpath either by the server address or the deprecated server path option it’s strongly recommended that when users are integrating the /api/authz/* or /api/verify endpoints do not include the configured path within those URLs. This is because the handler will listen on both the root path and the configured path and several misconfiguration issues can be avoided by doing this.

Integration Implementation#

Authelia is capable of being integrated into many proxies due to the decisions regarding the implementation. We handle requests to the authz endpoints with specific headers and return standardized responses based on the headers and the policy engines determination about what must be done.

Destination Identification#

Broadly speaking, the method to identify the destination of a request relies on metadata headers which need to be set by your reverse proxy. The headers we rely on at the authz endpoints are as follows:

• X-Forwarded-Proto
• X-Forwarded-Host
• X-Forwarded-URI
• X-Forwarded-For
• X-Forwarded-Method / X-Original-Method
• X-Original-URL

The specifics however are dictated by the specific Authorization Implementation used. Please refer to the specific implementation you’re using.

User Identification#

A logged in user must be identified via standard means. Users are identified by one of two methods:

• A session cookie with the HTTP only option set, and the secure option set meaning the cookie must only be sent over the HTTPS scheme.
• The Proxy-Authorization header utilizing the basic authentication scheme.

Response Statuses#

Authelia responds in various ways depending on the result of the authorization policies.

When the user is authenticated and authorized to access a resource we respond with a HTTP 200 OK. When the user is not logged in and we need them to authenticate with 1FA, or if they are already authenticated with only 1FA and they need to perform 2FA, the user is redirected to the portal with:

• A HTTP 401 Unauthorized status if the original request was an XMLHTTPRequest provided Authelia is able to detect it.
• A HTTP 302 Found status if the original request had the GET or OPTIONS method verb.
• A HTTP 303 See Other status if neither of the above conditions is met.

When the user is denied either by a default policy, or by an explicit policy we respond with a HTTP 403 Forbidden status.

Response Headers#

With the exception of the 403 Forbidden and 200 OK status responses above, Authelia responds with a Location header to redirect the user to the authentication portal.

In the instance of a 200 OK status response Authelia also responds with various headers which can be forwarded by your reverse proxy to the backend application which are potentially useful for SSO depending on if the backend application supports it.

See the Trusted Header SSO documentation for more information.