Running Apache NiFi behind a reverse proxy or load balancer

Why teams put Apache NiFi behind a reverse proxy or load balancer

Teams put Apache NiFi behind a reverse proxy or load balancer when the NiFi UI or REST API must be reached through a shared hostname, a managed TLS endpoint or a cluster front end instead of a raw node address. A single-node proxy is usually enough for a lone instance that operators reach from a corporate network. A clustered deployment needs the load balancer to keep each user's session on one node, which is the affinity question this page works through. The proxy does not replace NiFi's own security. It becomes the address that browsers, scripts and identity providers see, so its hostname and scheme must match what NiFi is configured to expect. The starting point matters. When no security configuration is provided, NiFi binds to 127.0.0.1, so the UI is reachable only through the loopback interface, according to the NiFi administration guide. Any proxy you place in front of NiFi therefore has to reach that interface, or you must deliberately change the binding and secure the listener first. Confirm the bind address and HTTP or HTTPS port in your build before you write any proxy configuration, and confirm which authentication provider you will use, since single-user, LDAP, OpenID Connect, SAML 2.0 and X.509 client certificate authentication each handle the forwarded hostname and certificate details differently. A single node behind a proxy mainly needs correct hostnames, forwarded headers and TLS termination. A cluster adds a second requirement: every request from one user's browser session must reach the node that issued the session, or the user can receive 401 responses even after a successful sign-in. Plan the cluster's state coordination early, because clusters can coordinate through embedded or external ZooKeeper or through Kubernetes ConfigMaps or Leases, and that choice determines what your front end must balance. Ask your team to document which of these two shapes you are building before you choose the load balancer product.

Proxy options and when each fits NiFi

This table compares NGINX, HAProxy and a cloud load balancer for fronting NiFi, along with TLS termination at the proxy versus end-to-end TLS to NiFi. Read each row against your own operating model: who runs the component, how it forwards headers and paths, and whether it can keep a browser session on one node. The main takeaway is that the sticky session and header behavior matter more to NiFi than raw feature lists, so confirm those with each vendor before you choose.

Option	Operational fit	Header and root path handling	Sticky session support and ownership
NGINX, self-managed	Suits teams that already run NGINX and want configuration kept in version control on hosts they control	You set forwarded headers and the root path in the server configuration, and NiFi must be told which proxy hosts to trust	Affinity is configured by you, and you own the health checks and failover behavior
HAProxy, self-managed	Suits teams that want a dedicated load balancer with detailed backend health and connection controls	Headers and path rewrites are set in the frontend and backend sections, and must match NiFi's proxy settings	Session persistence is configured by you, and you own its tuning and monitoring
Cloud load balancer	Suits teams in a cloud account that prefer a managed listener and target group model	Header and path handling depends on the provider and listener type, so confirm which forwarded headers reach NiFi	Stickiness options and their duration depend on the provider, and the provider runs the component
TLS terminated at the proxy	Simplifies certificate handling on one tier, but traffic between proxy and NiFi is then plain unless you add a second layer	NiFi must trust the proxy's forwarded scheme and host, so the proxy must send them consistently	No effect on affinity, but the certificate and its renewal sit with the proxy owner
End-to-end TLS to NiFi	Keeps encryption on every hop, at the cost of managing trust stores on the proxy and NiFi	The proxy must present a client trust path NiFi accepts, and certificate names must match the host used in browsers	No effect on affinity, but certificate rotation must be coordinated across both components
Single node versus cluster	A single node has no affinity requirement, while a cluster needs one browser session to stay on one node	The same header rules apply to both, so test the cluster configuration before adding nodes	Missing affinity in a cluster is the usual cause of 401 errors, so confirm stickiness during testing

Configuration areas: root path, proxy headers and allowed proxy hosts

When NiFi is served under a sub-path such as /nifi on a shared hostname, NiFi must know the prefix users see in the browser so that the links, redirects and static asset references it generates still pass through the proxy. The setting that carries this is documented in the NiFi System Administrator's Guide as nifi.web.proxy.context.path in nifi.properties. The proxy rewrite and this value must agree, because a mismatch sends the browser to paths the proxy never routes.

Context path value: Set the property to the exact prefix users type, and confirm the expected format (leading slash, trailing slash) for your NiFi version.
Matching proxy rewrite: NGINX location blocks or HAProxy path rules must forward requests so that the path NiFi receives matches the configured value. A mismatch typically produces blank pages or missing scripts.
Login and redirect loops: Redirects built with the wrong prefix send users to addresses the proxy does not route, which often looks like a loop or a page that never finishes loading.
Root deployments: When the proxy owns a dedicated hostname, serving NiFi at the root path avoids rewrite rules entirely and removes this class of error.

After login, check the browser network log for requests that carry an unexpected prefix, and confirm the property name against the documentation for your exact release.

NiFi builds the URLs it returns from the request it receives, so the proxy must describe the public address the user connected to. It does this through forwarded headers that carry the original scheme, host, port and context path. The administration guide documents header names such as X-ProxyScheme, X-ProxyHost, X-ProxyPort and X-ProxyContextPath, and the exact set your version honors should be confirmed before you write the proxy configuration. Without these values, NiFi falls back to the internal view of the request.

Host and scheme: Send the public host name and https as the scheme, so generated links and cookie domains match what the browser uses. Mismatches produce redirects to internal host names.
Port: Send the public port when it differs from the default. A proxy listening on 443 that forwards to an internal port otherwise leaks the internal port into links.
Context path header: When the proxy strips the prefix, send the prefix in the context path header so NiFi builds links that include it.
Header overwriting: Set these headers in the proxy and overwrite any values the client sent, so a user cannot spoof the public host or scheme.
Proxied entities: Headers used to pass a chain of user identities are a separate concern, especially with certificate-based access. Review them in the guide before enabling any of them.

Compare the URLs NiFi returns in a login redirect with the public address, and confirm the header names your version reads before you deploy.

NiFi keeps a list of host and port values it accepts from proxied requests. The administration guide documents this as nifi.web.proxy.host in nifi.properties. The list is a security control as well as a routing aid: it limits which Host values NiFi will serve, so an entry that is too broad widens the attack surface, and an entry that is missing causes requests to be refused before the UI loads. Confirm the expected list format for your version, including whether ports must be written explicitly.

Public names: Include every name that users or the load balancer send in the Host header, starting with the public host name.
Port inclusion: When the public URL uses a non-default port, list the host with that port so it matches the Host header exactly.
Internal names: Add internal names only when the proxy forwards them to NiFi. Extra entries are rarely needed and enlarge what NiFi accepts.
Health checks: Load balancer health checks often send a different Host value. Identify which name they use and allow it, or the node may be marked unhealthy.
Consistent changes: Make the same change on every node in a cluster, and restart or reload according to your version's requirements, so that all nodes accept the same requests.

Test from each public name and from the health check path after every change, and keep the list in version control with the rest of the proxy configuration.

How to set up the proxy in front of NiFi step by step

This sequence takes NiFi from a bare install to a proxied endpoint that users and clusters can reach reliably. Each step closes with a check, so the team knows the layer below works before it adds the next one.

Decide the TLS termination model
The platform owner and the security lead decide where TLS ends: at the proxy only, at the proxy and again at NiFi (re-encryption), or on a cloud load balancer that passes traffic through. Record the choice with the certificate authority, the certificate names users will type, and who renews the certificates. This decision drives every later setting, so it comes first. The step is done when the team has a one-page diagram showing each hop and whether it is encrypted. Confirm the choice with your own network and security standards before you proceed.
Configure NiFi security and proxy host settings
The NiFi administrator sets the HTTPS properties in nifi.properties so NiFi listens on the interface the proxy can reach, and adds the proxy's host name and port to the allowed proxy hosts setting. Without this allow-list, NiFi rejects requests that arrive with forwarded headers. Confirm the authentication provider and the exact user identity the proxy will present. Restart NiFi, then check the logs for a clean startup and confirm the listening address with a local request from the proxy host. The step closes when a direct request from the proxy host returns the NiFi login page over the expected protocol.
Set the root path and forwarded headers
The proxy administrator maps a public path, such as a sub-path or the root, to NiFi's internal address and sets the forwarded headers NiFi uses to build links and redirects. The proxy must send the original host, protocol and port, and the path prefix must match the root path value configured on the NiFi side. Mismatches here cause broken redirects and assets that load from the wrong address. Record the exact header names and values in your configuration repository. The step is done when a request to the public URL reaches the login page and the redirect target shows the public address, not the internal one.
Enable session affinity for clusters
For a clustered deployment, the load balancer administrator enables session affinity so that every request from one browser session reaches the same NiFi node. NiFi keeps user session state on the node that authenticated the user, so a request routed to another node is rejected with an authorization error, often shown as a 401. Use the affinity method your load balancer supports, such as a cookie or source address, and confirm the setting with the vendor documentation. The step is done when repeated requests from one browser stay on one backend node in the load balancer's access logs.
Verify login through the proxy
The test owner signs in through the public URL using each authentication method that users rely on, such as LDAP, OpenID Connect or client certificates. Sign-in should complete, the browser should land on the canvas, and the session should survive a page refresh. Failures at this point usually trace back to proxy headers or the allowed proxy host list, so compare the logs against the forwarded headers you set. The step is done when a test user signs in and out successfully and the NiFi log shows the expected user identity rather than the proxy's address.
Verify UI assets and WebSocket updates
The test owner opens the canvas, checks that all JavaScript, CSS and image files load without errors in the browser developer tools, and confirms that the live status updates on processors and the bulletin board appear without a manual refresh. Live updates depend on WebSocket connections, so the proxy must allow the upgrade and keep the connection open long enough for the session. A stalled status panel or blocked asset usually points to a missing upgrade header or an incorrect path prefix. The step is done when the canvas updates in real time and the browser console shows no failed requests.
Verify node-level requests in clusters
For each node, the cluster administrator sends a request through the proxy that targets that node's cluster view, then checks the cluster page for all nodes showing as connected. Confirm that requests for flow changes, provenance and queue listings succeed regardless of which backend node receives them. A node that cannot be reached through the proxy will appear disconnected or return intermittent 401 errors. The step is done when every node reports as connected in the cluster view and a sequence of test requests succeeds across the backend pool. Repeat this check after each proxy or NiFi configuration change.

Why missing affinity causes 401 errors in a NiFi cluster

In a NiFi cluster, a 401 error often means that a request carrying a login token issued by one node reached a different node that does not accept it. The most common case is the browser UI. A user signs in, the node that handled the login issues the credentials the UI sends on every later call, and a round-robin load balancer may send the next call to another node. Confirm how your NiFi version binds authentication state in the NiFi administration guide, but plan on the assumption that a session is tied to the node that created it. Typical symptoms include users being logged out at random, actions that succeed and then fail after a refresh, and API scripts that fail intermittently with 401. A 403 points to authorization, so treat it as a separate problem.

Start the diagnosis at the proxy. Review the access log and check whether consecutive requests from one client, identified by the same session cookie or bearer token, reach different upstream nodes. If the upstream address changes within a session, affinity is missing. Next, check nifi-app.log on each node for authentication errors at the same timestamps as the 401 responses. Confirm that every node shows as connected in the cluster view. Cluster coordination uses ZooKeeper, embedded or external, or Kubernetes ConfigMaps and Leases, and that layer tells nodes who belongs to the cluster. It does not route a browser to the node holding its session, so the proxy must do that. Also confirm that all nodes use the same authorizer and identity provider configuration, because drift there produces similar symptoms.

The fix is session affinity on the load balancer. Cookie-based affinity is usually easier to reason about than source IP hashing, because many users behind one corporate NAT address would all be pinned to the same node. Whichever method you choose, test it by sending repeated requests from one browser and one script, and confirm they stay on one node. Set the affinity timeout to match the session lifetime your NiFi configuration uses, and confirm that value with your team before go-live. Expect users to sign in again after a node is restarted or removed, and include that in the runbook. Affinity keeps sessions stable but does not replace a healthy cluster, so resolve any disconnected node before tuning the balancer.

Security considerations for proxied NiFi access

A reverse proxy in front of NiFi becomes part of its security boundary. The cards below cover where TLS is ended, which hosts NiFi trusts to speak for users, which paths are published, how the proxy itself is protected, and how NiFi's authentication matches what the proxy passes along.

TLS termination points

Decide whether the proxy ends TLS and sends plain HTTP to NiFi, or re-encrypts traffic to NiFi over HTTPS. Ending TLS at the proxy alone leaves traffic between the proxy and NiFi unencrypted on any network segment that others can read. Confirm the certificate chain, cipher policy and protocol versions on both hops, and check whether client certificate authentication needs to pass through the proxy unchanged.

Allowed proxy hosts list

NiFi uses the proxy host list in its configuration to decide which upstream addresses may supply forwarded host and path headers. Keep this list to the exact proxy addresses that connect to NiFi, and avoid wildcards or broad subnets. Review the list whenever the proxy fleet changes, because an overly broad entry lets any host in that range present itself as a trusted front end.

Exposing only intended paths

Publish only the NiFi UI, API and login paths that users and automation need. Block administrative and internal endpoints at the proxy, and deny unknown paths by default instead of passing everything through. Test each published path with an unauthenticated request and confirm that the response is a login redirect or an access error, not data.

Protecting the proxy admin interface

The proxy's own status pages, dashboards and configuration APIs are a second administrative surface. Bind them to a management network or loopback address, require their own authentication, and remove default pages and debug modules from production builds. A compromised proxy admin panel can change routing or headers and bypass NiFi's controls entirely.

Aligning NiFi authentication with the proxy

Choose one authentication provider for NiFi, such as LDAP, OpenID Connect, SAML 2.0 or X.509 client certificates, and confirm that the proxy forwards exactly the identity data that provider expects. If the proxy performs sign-in, NiFi must trust only the identity headers it sets. Kerberos is deprecated in the supplied NiFi guidance, so plan new deployments around the other options.

Questions teams ask before running NiFi behind a proxy

What drives the cost of putting NiFi behind a reverse proxy or load balancer?

The cost follows the amount of configuration and testing, not the proxy product itself. The main drivers are the number of proxies or load balancers in the path, the number of NiFi nodes, the TLS model (where certificates terminate and whether traffic is re-encrypted to NiFi), how the identity provider is wired in (LDAP, OpenID Connect, SAML 2.0 or X.509 client certificates), and how much testing the change needs before it reaches production. Each of these adds design decisions, configuration files to keep consistent and test cases to run. A quote should list each proxy, each node, each authentication path and each test scenario as separate line items, so you can see what is one-time work and what recurs during upgrades.

How long does a NiFi reverse proxy setup usually take?

The duration depends on how many components are involved and how many decisions are still open when the work starts. A single-node NiFi behind one proxy with an existing certificate and a known identity provider is a smaller job than a clustered deployment with sticky sessions, several proxy layers and SAML or OpenID Connect sign-in that has to work through the proxy. Most of the time goes to agreeing the root path, the proxy host allow list, the header handling and the TLS model, then testing login, UI refresh and cluster node failover. Ask any partner to present the schedule as phases tied to those decisions, and to name which phases depend on your team's input.

What must our internal team provide before the work starts?

Gather the information that the design depends on before the first configuration change. Typical inputs are:

A network diagram showing the client path, each proxy or load balancer, firewalls and every NiFi node address.
The certificates and private keys you plan to use, their chain, their expiry dates and the hostnames they cover.
Identity provider details: issuer or metadata URLs, client registrations, group or claim mappings and the callback hostname that users will see.
The planned public hostname and any root path that users will type into the browser.
Your load balancer or proxy standards, including who operates it and how changes are approved.
Log, monitoring and change-management requirements, so the test evidence matches your process.

Missing items usually show up later as rework during testing.

Can an experienced administrator set this up alone?

Often yes for a single node behind one proxy with a simple authentication setup, provided the administrator has working knowledge of NiFi's nifi.properties file, the proxy's header handling and the identity provider. The work becomes harder to do alone when several teams own different pieces: the network team owns the load balancer, the identity team owns the provider, and the platform team owns NiFi. In that case the risk is less technical than coordination, because a sticky session setting or a proxy host entry can be changed by someone else without notice. A useful test is whether one person can explain, test and roll back every layer. If not, plan for a second reviewer or an outside partner for the design and test phases.

Why does NiFi return 401 errors behind a load balancer?

In a cluster, a user's login state is held by the node that accepted the login, so later requests from the same browser must reach that same node. Without sticky sessions (session affinity) at the load balancer, a follow-up request can land on another node that does not recognize the token, and the user sees a 401 error. Check the affinity setting first, then confirm that the cookie or header the load balancer uses for affinity survives every proxy layer. A single-node deployment does not have this problem, so 401 errors there usually point to proxy host or header configuration instead.

Does terminating TLS at the proxy change the security requirements?

It changes where the trust boundary sits, and it does not remove the need for protection inside your network. If the proxy terminates TLS and forwards plain HTTP to NiFi, traffic between the proxy and NiFi is unencrypted, and that segment must be isolated or accepted as a documented risk. If the proxy re-encrypts to NiFi, you need certificates that NiFi trusts for the backend connection and a plan to rotate them. Either way, the authentication configuration in NiFi must match the public URL users see, or sign-in redirects will fail. Record the chosen model in your security design so auditors and engineers can see the same decision.

Which parts of this work should we test before go-live?

Test the path a real user takes, and the failure cases your cluster must survive. At minimum, test sign-in through the public hostname for each enabled authentication method, UI navigation under the configured root path, a browser session that is reloaded and switched between nodes, the behavior when one node is stopped, and certificate validation from client machines. Add checks that the proxy forwards the headers NiFi expects and rejects requests from hosts that are not on the allow list. Keep the results with the change record. Ask for the test plan as a written deliverable before the build starts, so acceptance criteria are agreed in advance.

Will the configuration need to change after upgrades?

Yes, it can. Proxy-related settings live in NiFi's configuration files and in the proxy, so each NiFi upgrade should include a review of those settings alongside the usual release notes. NiFi 2 changes several configuration and migration points compared with the 1.x line, so the proxy design should be reviewed as part of any version move, not after it. Ask your partner or your team to document the affected keys, the proxy rules and the test cases that must be rerun after each upgrade, and to schedule that review as recurring work.

Limits to confirm in your environment before you deploy

A reverse proxy or load balancer changes how NiFi sees requests, sessions and certificates, so several settings depend on facts only your environment can confirm. The cards below cover the version, the proxy product, the certificate chain and the load balancer affinity you need, in the order most teams hit them.

NiFi version and documented proxy settings

Proxy behavior and the properties that control it can change between NiFi 1.x and 2.x. Confirm which version you run, then read the proxy and host settings for that exact release in the administration guide before writing any proxy configuration. Record the version in your change ticket so a later upgrade starts from the right reference. Do not copy settings from older blog posts or forum threads without checking them against your release.

Proxy product WebSocket and session support

NiFi's UI relies on long-lived connections and session state, so the proxy must forward upgrade requests and keep the client on a consistent path. Confirm with your proxy vendor and your own test whether the chosen product and version handle WebSocket upgrades, timeouts and buffering the way NiFi needs. Test a real flow edit session through the proxy rather than relying on a loaded page alone.

Certificate chain and hostname match

The hostname users type must match the certificate presented at the edge, and the full chain must be installed where the proxy expects it. If you re-encrypt to NiFi, confirm that NiFi's own certificate matches the name the proxy uses upstream and that the trust store contains the issuing authority. Check certificate expiry dates and the renewal process before go-live, because an expired certificate blocks every user at once.

Load balancer affinity for clusters

A cluster needs each user's requests to reach the node that holds their session and token. Confirm whether your cloud load balancer offers the cookie-based or source-address affinity method you plan to use, how it behaves when a node is removed, and what the idle timeout is. If the affinity method cannot keep a session on one node, expect intermittent 401 errors during normal use, and plan a test that changes node membership.

Allowed proxy hosts and redirect behavior

NiFi validates the host and port of incoming requests against a configured list, and a mismatch can produce rejected requests or redirects to internal addresses. Confirm the exact external hostname, port and any path prefix your users will use, and list every proxy address that NiFi must trust. Verify that redirects and links in the UI point to the external name after the change, not an internal node address.

Identity provider callback URLs

If you sign in with LDAP, OpenID Connect, SAML 2.0 or X.509 certificates, the external address must also match what the identity provider expects. Confirm the callback or assertion consumer URLs registered with the provider, and whether they change when the root path changes. Test sign-in through the proxy path before handing the environment to users, since a mismatch looks like a generic login failure.

How proxy settings change when moving from NiFi 1.x to 2.x

NiFi 1.x is past its final support date, so proxy configuration written for 1.x should be reviewed as part of the planned move to NiFi 2. The NiFi downloads page lists December 8, 2024 as the end-of-support date for 1.28.1, the last minor release of the version 1 series, and the project strongly encourages users to upgrade to NiFi 2. The project's stated reason is that 1.x depends on Jetty 9.4, Spring Framework 5.3 and AngularJS 1.8, which cannot be upgraded within that line, so the platform underneath your proxy will not receive further maintenance.

The migration path is staged. The NiFi migration guidance requires upgrading to NiFi 1.27.0 before moving to 2.0.0, and it changes the flow configuration file from flow.xml.gz to flow.json.gz. Proxy-related settings such as nifi.web.proxy.host and nifi.web.proxy.context.path live in nifi.properties, which you will review at each step. Confirm the exact property names and any defaults that changed for your target 2.x release against that guidance before editing the new configuration, rather than copying the 1.x file forward.

Retest the whole proxy path after the move, not only the login page. Check the root path mapping, that the UI loads its assets through the proxy, that cluster sticky sessions still route each user to one node, and that requests from the proxy are accepted without 401 or 403 responses. Run these checks against the 2.x instance in a non-production environment first, and record the results so the cutover has a documented baseline. Ask your partner or internal team to confirm the proxy host list and TLS termination point are unchanged for the new version.

How DeployOpen works on this

DeployOpen plans, builds, documents and supports NiFi proxy work inside your own infrastructure, whether the front end is NGINX, HAProxy or a cloud load balancer. We start from your network paths, certificate ownership and cluster layout, then deliver a configuration you can review, test and operate on your own.

How we scope

We map every hop between users, the proxy, and each NiFi node, including TLS termination points and certificate owners.
The written scope names the proxy product, root path, allowed proxy hosts and whether the NiFi cluster needs sticky sessions.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts; ongoing support is available as a retainer.

How we build

We configure proxy headers, the NiFi proxy host list and root path mapping in a version-controlled change set.
We set up session affinity for clustered NiFi and test that login, UI and API calls stay on the same node.
We reproduce expected 401 and 403 failures in a staging environment so the team can recognize them before production.

How we hand over

You receive the proxy configuration, NiFi property settings and a test checklist covering login, UI loading and API access.
Runbooks describe how to add or remove a node, rotate proxy certificates and diagnose affinity or header problems.
We document each design decision, including why TLS terminates where it does, so your team can review future changes.

How we support

After handover, we can review proxy changes made during NiFi upgrades, since the proxy and NiFi settings must stay aligned.
Retainers cover ongoing configuration reviews, patching of the proxy and periodic re-testing of login and cluster routing.
We confirm with your own environment and with the NiFi administration guide before each upgrade, rather than assuming settings carry over.