# Proxy FusionAuth Learn more about HTTP proxies and FusionAuth. > For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt) 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. ```mermaid sequenceDiagram participant u as User Agent participant p as Proxy participant f as FusionAuth u ->> p : Request p ->> f : Request f -->> p : Send page p -->> u : Send page ``` A typical proxy configuration. 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](https://github.com/fusionauth/fusionauth-issues/issues). ## 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](https://github.com/FusionAuth/fusionauth-issues/issues/404)) * 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](https://github.com/FusionAuth/fusionauth-issues/issues/88)) ## How To Use a Proxy This section won't discuss setting up your proxy or proxy specific configuration. For more on that, please consult your proxy package's or server's documentation. To correctly set up a proxy in front of FusionAuth, you must forward all requests to FusionAuth, and you must also set the correct headers. ### Headers To Set Below is a list of the headers you must set when using a proxy with FusionAuth. If you do not set these headers correctly, FusionAuth will not function correctly. You may be unable to log in to the Admin UI, redirect URLs may be sent incorrectly, or other functionality may not work. *Proxy Headers To Set* | Header | Example Value | Notes | | --- | --- | --- | | `X-Forwarded-Proto` | `https` | Typically this will be `https`, as it is typical to run FusionAuth in production using HTTPS. This ensures any redirects and cookies are sent with the appropriate scheme. This will be the scheme of the proxy server. | | `X-Forwarded-Host` | `auth.example.com` | The original host requested by the client in the `Host` HTTP request header. This will be the hostname of the proxy server. | | `X-Forwarded-Port` | `443` | The original port requested by the client. This will be the port of the proxy server. | | `X-Forwarded-For` | `204.98.1.1` | The originating IP address of the client. This varies and is used for logging IP addresses and [enforcing ACLs](https://fusionauth.io/docs/apis/ip-acl.md). | | `X-Forwarded-Server` | `auth.example.com` | The hostname of the proxy server. It should be set by every proxy server in the proxy chain. This may be different from `X-Forwarded-Host` if there are two or more proxy servers. | Let's say FusionAuth is running 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` * `X-Forwarded-Port`: `443` 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. Here is documentation for common proxy servers, describing how to configure these headers: * [Cloudflare](https://developers.cloudflare.com/rules/transform/request-header-modification/) * [NGINX](https://nginx.org/en/docs/http/ngx_http_headers_module.html) * [Apache](https://httpd.apache.org/docs/current/mod/mod_headers.html) * [Caddy](https://caddyserver.com/docs/caddyfile/directives/header) * [Amazon CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html) ### Caching FusionAuth disallows caching of non-static assets such as HTML pages with the [Cache-control: no-store header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). 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](https://github.com/FusionAuth/fusionauth-contrib/tree/main/Reverse%20Proxy%20Configurations). Note If you are running version `1.41.0` or later, please make sure your proxy is using `HTTP/1.1` instead of `HTTP/1.0`. We do not support `HTTP/1.0` anymore. We figured since it has been [supported since 1997](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Evolution_of_HTTP), `HTTP/1.1` was a good option. ### 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. ```mermaid sequenceDiagram participant u as User Agent participant p1 as Proxy 1 participant p2 as Proxy 2 participant f as FusionAuth u ->> p1 : Request p1 ->> p2 : Request p2 ->> f : Request f -->> p2 : Send page p2 -->> p1 : Send page p1 -->> u : Send page ``` A proxy configuration with multiple proxies. 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](https://fusionauth.io/docs/concepts/types/tenants.md) 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.com` and a FusionAuth tenant Id of `edfcf8d6-3044-4b5b-a52a-016f17f635d6`. * Hooli has an endpoint at `hooli.example.com` and a FusionAuth tenant Id of `6fec7aed-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](https://fusionauth.io/docs/concepts/integration-points.md#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 plan). In either case, disallow traffic to FusionAuth not originating from the proxy. ### Restricting the Admin UI The Admin UI is served from `/admin` and makes background requests to `/ajax`. If your administrators work from known networks, configure your proxy to reject requests to both paths from any other source IP address. The hosted login pages and the APIs don't use either path, so blocking them doesn't affect your users. ### Security Headers FusionAuth sends `X-Frame-Options: DENY` on its hosted login and account pages, which stops other sites from framing the login page. To allow framing by specific origins, use the Application's **Authorized request origin URLs** setting. Don't set `X-Frame-Options` at the proxy, because a second header causes inconsistent browser behavior. Add the following response headers at your proxy: ```plaintext Strict-Transport-Security: max-age=31536000; includeSubDomains X-Content-Type-Options: nosniff Referrer-Policy: strict-origin-when-cross-origin ``` `Strict-Transport-Security` tells browsers to only use HTTPS for your FusionAuth domain. Only send it once HTTPS works for the domain and every subdomain, because browsers remember it for the full `max-age`. If you also want a `Content-Security-Policy`, deploy it as `Content-Security-Policy-Report-Only` first. The default Themes use inline scripts and styles, so a strict policy breaks the hosted login pages. See the [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/) for more about each header. ## Trusting Proxies When running behind a proxy, FusionAuth uses the `X-Forwarded-For` header to resolve the client's IP address. To prevent man-in-the-middle attacks or IP spoofing via the `X-Forwarded-For` header, FusionAuth allows you to specify a list of trusted proxies. See the [networking configuration](https://fusionauth.io/docs/deploy/harden/networking.md) section for more information. ## Troubleshooting If you see the below error when you are trying to log in, ensure that all your headers are set correctly. Common Proxy Error Message ```plaintext 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. When you log into the FusionAuth Admin UI, you may receive additional troubleshooting information. If you see the below image, this indicates you need to configure the headers for FusionAuth to operate correctly. ![The proxy warning message in the Admin UI.](https://fusionauth.io/img/docs/operate/deploy/warning-message.png) The specific errors you see may be different based on the particular headers you are missing. ## Proxying Requests From FusionAuth This guide covers proxying requests *to* FusionAuth, in order to add a layer of indirection between your users and FusionAuth. The benefits are listed in [Why Use a Proxy](#why-use-a-proxy). If you are self-hosting, you can also proxy requests *from* FusionAuth, such as [webhooks](https://fusionauth.io/docs/events.md) or [connector requests](https://fusionauth.io/docs/users/provision/connectors.md). You can read more about that in the [Configuration Reference](https://fusionauth.io/docs/deploy/production/configuration.md). Look for the `proxy.*` configuration values. This functionality is not available in FusionAuth Cloud. ## FusionAuth Cloud Instances If you are using a proxy with a FusionAuth Cloud instance, see our [Using a Proxy with FusionAuth Cloud](https://fusionauth.io/docs/cloud/operate/configure-proxy.md) documentation for more Cloud-specific requirements. ## Limits There are no limits on using a proxy with FusionAuth. You can use a proxy with self-hosted FusionAuth or with FusionAuth Cloud. Related [Cloud Proxy Learn how to run FusionAuth in various cloud environments. proxy configurationreverse proxy](https://fusionauth.io/docs/cloud/operate/configure-proxy.md) [APIs Retrieve System Health API API documentation for the FusionAuth Retrieve System Health API. load balancer](https://fusionauth.io/docs/apis/system/retrieve-system-health.md) [Authorization HAProxy API Gateway Learn about the HAProxy JWT integration. load balancer](https://fusionauth.io/docs/authorization/api-gateways/haproxy-api-gateway.md) [Cloud Instance IP Addresses Get the IP addresses used to access your FusionAuth Cloud instance. network configuration](https://fusionauth.io/docs/cloud/reference/instance-ip-addresses.md) --- ## Other pages in Production > For the full index of this section, see [Deploy](https://fusionauth.io/docs/llms-deploy.txt). - [FusionAuth CLI](https://fusionauth.io/docs/deploy/production/cli.md): Learn about the FusionAuth CLI tool. - [Configure a FusionAuth sCluster](https://fusionauth.io/docs/deploy/production/cluster.md): Learn how to set up a multi-node FusionAuth cluster. - [Configuration Reference](https://fusionauth.io/docs/deploy/production/configuration.md): Learn about the configuration options for FusionAuth. - [Air-gapping](https://fusionauth.io/docs/deploy/production/install/air-gapping.md): Run FusionAuth with no network access (air-gapped). - [Install a Database](https://fusionauth.io/docs/deploy/production/install/database.md): Learn how to install the database that FusionAuth will use to store user data. - [Customize Docker Images](https://fusionauth.io/docs/deploy/production/install/docker-configuration.md): Learn how to configure a Docker image containing FusionAuth to meet the needs of your application. - [Install FusionAuth App](https://fusionauth.io/docs/deploy/production/install/fusionauth-app.md): Learn how to install FusionAuth App on a production server with Docker or from a package. - [Packages](https://fusionauth.io/docs/deploy/production/install/packages.md): Learn how to determine which installation packages you need. - [Install a Search Engine](https://fusionauth.io/docs/deploy/production/install/search.md): Learn how to install a search engine for your FusionAuth instance. - [Silent Mode](https://fusionauth.io/docs/deploy/production/install/silent-mode.md): This is a guide to using silent mode during FusionAuth install and updates. - [Microsoft Azure Kubernetes Service (AKS)](https://fusionauth.io/docs/deploy/production/kubernetes/aks.md): Learn how to provision an AKS cluster in Microsoft Azure. - [Elastic Kubernetes Service (EKS)](https://fusionauth.io/docs/deploy/production/kubernetes/eks.md): Learn how to provision an EKS cluster in AWS. - [Deploy with k8s](https://fusionauth.io/docs/deploy/production/kubernetes/fusionauth-deployment.md): Learn how to deploy FusionAuth in a Kubernetes Cluster. - [Google Kubernetes Engine (GKE)](https://fusionauth.io/docs/deploy/production/kubernetes/gke.md): Learn how to provision a GKE cluster in Google Cloud (GCP). - [Kubernetes](https://fusionauth.io/docs/deploy/production/kubernetes.md): Learn how to deploy and test FusionAuth using Kubernetes. - [Local Cluster with minikube](https://fusionauth.io/docs/deploy/production/kubernetes/minikube.md): Learn how to provision minikube for local development and testing of FusionAuth kubernetes deployments. - [AWS](https://fusionauth.io/docs/deploy/production/marketplaces/aws.md): Learn how to use FusionAuth with the AWS Marketplace. - [DigitalOcean](https://fusionauth.io/docs/deploy/production/marketplaces/digitalocean.md): Learn how to use FusionAuth with the DigitalOcean Marketplace. - [Google Cloud](https://fusionauth.io/docs/deploy/production/marketplaces/google-cloud.md): Learn how to use FusionAuth with the GCP Marketplace. - [Install from a Marketplace](https://fusionauth.io/docs/deploy/production/marketplaces.md): Learn how to install FusionAuth using cloud marketplaces or templates. - [Render](https://fusionauth.io/docs/deploy/production/marketplaces/render.md): Set FusionAuth up on Render from a Blueprint. - [Server Layout](https://fusionauth.io/docs/deploy/production/server-layout.md): Learn about the different server layouts that FusionAuth can be installed with to optimize performance and security. - [Start and Stop a Production Instance](https://fusionauth.io/docs/deploy/production/start-and-stop.md): Learn how to start and stop the FusionAuth services on a production server, in Docker, and in Kubernetes. - [System Requirements](https://fusionauth.io/docs/deploy/production/system-requirements.md): Learn the minimum system requirements required to install and run FusionAuth. - [Manage FusionAuth With Terraform](https://fusionauth.io/docs/deploy/production/terraform.md): Learn how to create and change FusionAuth configuration with the FusionAuth Terraform provider.