FusionAuth and Proxies
Overview
While FusionAuth doesn’t require a proxy, using one offers additional flexibility.
What Is a Proxy
While the term is overloaded, for the purposes of this document, a proxy is any software which sits between your users and FusionAuth. Some or all requests to FusionAuth then pass through the proxy.
Proxies can be self-hosted or SaaS. Examples include:
-
NGINX
-
Apache
-
Caddy
-
Cloudflare
-
CloudFront
FusionAuth should work with any proxy that supports HTTP. If you find a proxy that isn’t supported, please open a GitHub issue with details.
Why Use a Proxy
While you can run FusionAuth without a proxy, there are a number of reasons why you might want one:
-
Have different domain names which point to different FusionAuth tenants; the proxy can map between domain names and tenant Ids
-
Block or throttle access based on request characteristics such as user agent
-
Cache CSS or other static assets for performance
-
Display custom error pages for 4xx or 5xx errors (see this issue for more)
-
Terminate TLS before requests reach FusionAuth
-
Add additional request processing logic
-
Have FusionAuth requests served from a non-standard path such as
/fa/(see this issue for more)
How To Use a Proxy
This section won’t cover setting up your proxy or proxy specific configuration. Instead, consult your proxy package’s documentation. However, you must forward all requests to FusionAuth, and you must also set the correct headers.
Here’s a list of the headers you must set:
-
X-Forwarded-Proto: typically this will behttps. This ensures any redirects and cookies are sent with the appropriate scheme. This will be the scheme of the proxy server. -
X-Forwarded-Host: The original host requested by the client in theHostHTTP request header. This will be the hostname of the proxy server. -
X-Forwarded-For: The originating IP address of the client. This varies and is used for logging IP addresses and enforcing ACLs. -
X-Forwarded-Server: The hostname of the proxy server.
Let’s say FusionAuth lives at https://example.fusionauth.io, and the proxy lives at https:///auth.example.com.
In this case, the headers would have the following values:
-
X-Forwarded-Proto:https -
X-Forwarded-Host:auth.example.com -
X-Forwarded-For: The client IP address -
X-Forwarded-Server:auth.example.com
Proxies may use different formats to set these headers. For example, IIS requires underscores and you must prepend the header with HTTP. X-Forwarded-Proto is HTTP_X_Forwarded_Proto. Please consult your proxy server’s documentation for more details.
Caching
FusionAuth disallows caching of non-static assets such as HTML pages with the Cache-control: no-store header.
Never cache FusionAuth non-static asset responses.
Common Proxy Configurations
The community has provided a number of example configurations for different proxies. You can view them in the GitHub repo.
Chaining Proxies
If needed, you can have multiple proxies for each request. This may be useful if one proxy handles custom domain names for tenants and another handles error pages.
With this pattern, every proxy in the chain must have the same value for X-Forwarded-Host, the hostname of the initial proxy. The initial proxy is Proxy 1 in the diagram above.
Doing so allows FusionAuth to set cookies and create redirects correctly.
However, X-Forwarded-Server should change as requests pass through each proxy.
Proxies and Tenants
If you are running multiple tenants in FusionAuth, a proxy can be useful to add the tenant Id to all requests for a given domain or path. Clients use the domain without needing to know or care about the tenant they are interacting with.
Suppose we have with two tenants, Pied Piper and Hooli:
-
Pied Piper has an endpoint at
piedpiper.example.comand a FusionAuth tenant Id ofedfcf8d6-3044-4b5b-a52a-016f17f635d6. -
Hooli has an endpoint at
hooli.example.comand a FusionAuth tenant Id of6fec7aed-cad3-45e0-bade-3c23cbeff070.
When an API request comes in to piedpiper.example.com, the proxy can append an X-FusionAuth-TenantId header with the value edfcf8d6-3044-4b5b-a52a-016f17f635d6. And, when an API request comes in to hooli.example.com, the proxy can append an X-FusionAuth-TenantId header with the value 6fec7aed-cad3-45e0-bade-3c23cbeff070.
When requesting the hosted login pages, you can append a tenantId query string. Simply add tenantId=edfcf8d6-3044-4b5b-a52a-016f17f635d6 for all requests to piedpier.example.com.
Locking FusionAuth Down
You may want to allow access to FusionAuth only through the proxy to enhance a defense in depth strategy. There are a few options to do so:
-
At the network level, using firewalls.
-
Using FusionAuth’s IP ACL feature (only available in the Enterprise edition).
In either case, disallow traffic to FusionAuth not originating from the proxy.
Troubleshooting
If you see the below error when you are trying to log in, ensure that all your headers are set correctly.
Something doesn't seem right. You have been logged out of FusionAuth. If you were attempting to log in please click 'Return to Login' to retry.If you are using FusionAuth Cloud, ensure that you have added the hostname of the proxy to which the initial request has been made to your list of custom domains.
For additional troubleshooting, it is helpful to remove any proxies one at a time and try to log in. This can help narrow down the source of the problem.
Limits
There are no limits on using a proxy with FusionAuth.
You can use a proxy with self-hosted FusionAuth or with FusionAuth Cloud.
When using a proxy with FusionAuth Cloud, ensure you have configured DDOS and other protections correctly at the proxy. FusionAuth Cloud’s built-in protection depends, in part, on receiving correct client IP addresses, but a proxy may mask or modify those and render this protection less effective.