fusionauth logo
search-interface-symbol
Downloads
Quickstarts
API Docs
SDKs
search-interface-symbol
talk to an expert
Log In
talk to an expert
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
      • Overview
      • Angular
      • C# .NET
      • .NET Core API
      • Express.js
      • Express API
      • Flutter
      • Java Spring
      • Laravel API
      • Python Django
      • Python Flask
      • React
      • Ruby on Rails
      • Ruby on Rails API
      • Vue.js
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Amazon Cognito
    • Duende IdentityServer
    • Firebase
    • Keycloak
    • Microsoft Azure AD B2C
    • Supabase
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • CLI
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • User Support Guide
    • Vulnerabilities
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
        • Okta
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
        • Okta
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
      • URL Validation
      • Integrations
        • CockroachDB
        • Salesforce
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Aiven
      • Google
      • PagerDuty
      • SendGrid
      • Tableau Cloud
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • Amazon API Gateway
      • HAProxy
      • Kong Gateway
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Angular
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
      • Vue
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Reg. Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Anonymous Users
      • Application Specific Email Templates
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
      • User Actions
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Self-Service Registration
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Client-side Password Validation
      • Examples
      • Helpers
      • Kickstart Custom Theme
      • Localization
      • Template Variables
      • Tailwind CSS
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Bootstrapping Login
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Hosted Backend
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    FusionAuth and Proxies

    Overview

    While FusionAuth doesn’t require a proxy, using one offers additional flexibility.

    • What Is a Proxy

    • Why Use a Proxy

    • How To Use a Proxy

      • Headers To Set

      • Caching

      • Common Proxy Configurations

      • Chaining Proxies

      • Proxies and Tenants

      • Locking FusionAuth Down

    • Troubleshooting

    • Proxying Requests From FusionAuth

    • Limits

    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.

    A typical proxy configuration.
    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.

    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 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 administrative user interface, redirect URLs may be sent incorrectly, or other functionality may not work.

    Table 1. 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.

    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

    • NGINX

    • Apache

    • Caddy

    • Amazon CloudFront

    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.

    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, 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.

    A proxy configuration with multiple proxies.
    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 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, 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.

    Common Proxy Error Message
    
    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 administrative user interface, 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 administrative user interface.

    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.

    If you are self-hosting, you can also proxy requests from FusionAuth, such as webhooks or connector requests. You can read more about that in the Configuration Reference. Look for the proxy.* configuration values. This functionality is not available in FusionAuth Cloud.

    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.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    How-to
    Blog
    Expert Advice
    Download
    Release Notes
    Subscribe for developer updates