Skip to content

docs: Document workaround to disable SNI checks #834

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs: Document workaround to disable SNI checks #834

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
255dcdf
Document workaround to disable SNI checks
lfrancke Aug 13, 2025
a72b3ca
Include documentation about what each property does
lfrancke Aug 14, 2025
15660c6
Update docs/modules/nifi/pages/troubleshooting/index.adoc
sbernauer Aug 18, 2025
c519480
Update docs/modules/nifi/pages/troubleshooting/index.adoc
sbernauer Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions Cargo.nix
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

44 changes: 40 additions & 4 deletions docs/modules/nifi/pages/troubleshooting/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,16 @@ spec:

== `HTTP ERROR 400 Invalid SNI`

You are very likely accessing a NiFi >= 2.0 stacklet using HTTPS to secure its WebUI and an Ingress in front of it.
The URL requested by the ingress-controller (such as nginx) needs to be the FQDN of the nifi service, not only the service name.
You can instruct nginx ingress to use the FQDN by setting the following annotation:
This error occurs when accessing NiFi 2.0 or later, which enforces https://en.wikipedia.org/wiki/Server_Name_Indication[SNI (Server Name Indication){external-link-icon}^] validation for HTTPS connections.
The hostname in the request must match one of the hostnames in NiFi's TLS certificate.
Copy link
Member

@NickLarsenNZ NickLarsenNZ Aug 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, this could go away with stackabletech/secret-operator#630, but might also require setting the external name in the NiFi properties.

No action needed, just mentioning it to keep it in people's minds.


NOTE: For complete technical background, see the https://issues.apache.org/jira/browse/NIFI-14858[upstream issue NIFI-14858{external-link-icon}^].

=== When using Ingress

If you're accessing NiFi through an Ingress controller, the ingress must forward requests using the FQDN of the NiFi service, not just the service name.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The controller doesn't necessarily handle traffic (eg: AWS Load Balancer Controller), and applies to more the Ingress (eg: Service, Gateway).

Suggested change
If you're accessing NiFi through an Ingress controller, the ingress must forward requests using the FQDN of the NiFi service, not just the service name.
If you're accessing NiFi through a Load Balancer or Reverse Proxy, it must forward requests using the FQDN of the NiFi service, not just the service name.


For nginx ingress, configure the `upstream-vhost` annotation to use the service FQDN:

[source,yaml]
----
Expand Down Expand Up @@ -53,7 +60,36 @@ spec:
# ...
----

For details please read on https://medium.com/@chnzhoujun/how-to-resolve-sni-issue-when-upgrading-to-nifi-2-0-907e07d465c5[this article].
For additional details, see https://medium.com/@chnzhoujun/how-to-resolve-sni-issue-when-upgrading-to-nifi-2-0-907e07d465c5[this article{external-link-icon}^].

=== When using Load Balancers or other proxies

When Load Balancers, API Gateways, or other proxy tools sit in front of NiFi, they may forward requests with hostnames that don't match NiFi's TLS certificates.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When Load Balancers, API Gateways, or other proxy tools sit in front of NiFi, they may forward requests with hostnames that don't match NiFi's TLS certificates.
When Load Balancers, API Gateways, or other proxy elements sit in front of NiFi, they might forward requests with hostnames that don't match NiFi's TLS certificates.

or

Suggested change
When Load Balancers, API Gateways, or other proxy tools sit in front of NiFi, they may forward requests with hostnames that don't match NiFi's TLS certificates.
When Load Balancers, API Gateways, or other proxy services sit in front of NiFi, they might forward requests with hostnames that don't match NiFi's TLS certificates.

This commonly occurs because:

* The proxy uses a different hostname than what's in NiFi's certificate
* NiFi is unaware of the external hostnames used to reach the proxy
* Certificate management in Kubernetes makes it complex to include all possible hostnames
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I disagree here.

It makes it difficult (to impossible) to add the dynamically assigned DNS name (for example, what AWS assigns to the Load Balancer, but that name isn't meant to be used directly - it is there for DNS records with the well-known name(s) to point to).

What is true here is that secret-operator doesn't allow other names to be added to the certificate (see stackabletech/secret-operator#630).


==== Workaround: Disable SNI validation

Since this scenario is common and difficult to resolve through certificate management, you can disable SNI validation in NiFi:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is through our own fault (well, secret-operator not supporting external names), so I think we need to revise this:

Suggested change
Since this scenario is common and difficult to resolve through certificate management, you can disable SNI validation in NiFi:
Since this scenario cannot currently be resolved through certificate management, you can disable SNI validation in NiFi:


[source,yaml]
----
nodes:
configOverrides:
nifi.properties:
nifi.web.https.sni.required: "false"
nifi.web.https.sni.host.check: "false"
----

These properties control NiFi's SNI validation behavior:

* `nifi.web.https.sni.required`: When `true`, NiFi requires that HTTPS requests include an SNI certificate. Setting to `false` allows connections without SNI certificates.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* `nifi.web.https.sni.required`: When `true`, NiFi requires that HTTPS requests include an SNI certificate. Setting to `false` allows connections without SNI certificates.
* `nifi.web.https.sni.required`: When `true`, NiFi requires that HTTPS requests include the SNI extension (containing the `server_name`). Setting to `false` allows connections without SNI certificates.

* `nifi.web.https.sni.host.check`: When `true`, NiFi validates that the SNI certificate's hostname matches the incoming request's hostname. Setting to `false` disables this hostname matching check.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might need to check this: Does the SNI Check check that the server_name is the same as the HTTP Host name? Or just that it is in the certificate, or both?

There is no SNI Certificate, so I'll rewrite that part, but we still need to ensure it is valid for Jetty 10.

Suggested change
* `nifi.web.https.sni.host.check`: When `true`, NiFi validates that the SNI certificate's hostname matches the incoming request's hostname. Setting to `false` disables this hostname matching check.
* `nifi.web.https.sni.host.check`: When `true`, NiFi validates that the SNI `server_name` is a valid Subject in the Certificate and that it matches the `host` header of the HTTP request. Setting to `false` disables this hostname matching check.

If we aren't sure about the host header matching, then:

Suggested change
* `nifi.web.https.sni.host.check`: When `true`, NiFi validates that the SNI certificate's hostname matches the incoming request's hostname. Setting to `false` disables this hostname matching check.
* `nifi.web.https.sni.host.check`: When `true`, NiFi validates that the SNI `server_name` is a valid Subject in the Certificate. Setting to `false` disables this hostname matching check.

I'm also trying to work out how we can mention Proxy Protocol v2 (PP2) in there... because load balancers can take the original server_name, and write it into the Authority header of the PP2. Jetty 10 supports PP2, so in theory it would check both PP2 Authority header (prepended to the TCP stream) or fall back to SNI server_name (in TLS Client Hello).

It's hard to validate that until we can have secret-operator add external Subject names. So maybe we can leave that for later.


WARNING: Disabling SNI validation reduces security by allowing connections with mismatched hostnames. Only use this workaround when proper certificate configuration is not feasible.

== `authorization_request_not_found` when using multiple NiFi nodes

Expand Down