Apache
/
nifi
mirror of https://github.com/apache/nifi.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

NIFI-12169 - Document alternatives to usage of TLS Toolkit 

This closes #7860

Signed-off-by: David Handermann <exceptionfactory@apache.org>
This commit is contained in:
Paul Grey 2023-10-05 13:35:47 -04:00 committed by exceptionfactory
parent 621e212640
commit 130c8e9903
No known key found for this signature in database
GPG Key ID: 29B6A52D2AAE8DBA
4 changed files with 54 additions and 1006 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
nifi-docs/src/main/asciidoc/administration-guide.adoc
View File

@ -111,7 +111,7 @@ The following table lists the default ports used by NiFi and the corresponding p
|Listener Bootstrap Port | `nifi.listener.bootstrap.port` | _random ephemeral_
|==================================================================================================================================================
NOTE: The ports marked with an asterisk (*) have property values that are blank by default in _nifi.properties_. The values shown in the table are the default values for these ports when <<toolkit-guide.adoc#tls_toolkit,TLS Toolkit>> is used to generate _nifi.properties_ for a secured NiFi instance. The default Certificate Authority Port used by <<toolkit-guide.adoc#tls_toolkit,TLS Toolkit>> is `9443`.
NOTE: The ports marked with an asterisk (*) have property values that are blank by default in _nifi.properties_.
=== Embedded ZooKeeper
The following table lists the default ports used by an <<embedded_zookeeper>> and the corresponding property in the _zookeeper.properties_ file.
@ -278,11 +278,11 @@ NiFi provides several different configuration options for security purposes. The
|==================================================================================================================================================
| Property Name | Description
|`nifi.security.keystore` | Filename of the Keystore that contains the server's private key.
|`nifi.security.keystoreType` | The type of Keystore. Must be `PKCS12` or `JKS` or `BCFKS`. JKS is the preferred type, BCFKS and PKCS12 files will be loaded with BouncyCastle provider.
|`nifi.security.keystoreType` | The type of Keystore. Must be `PKCS12` or `JKS` or `BCFKS`. PKCS12 is the preferred type, BCFKS and PKCS12 files will be loaded with BouncyCastle provider.
|`nifi.security.keystorePasswd` | The password for the Keystore.
|`nifi.security.keyPasswd` | The password for the certificate in the Keystore. If not set, the value of `nifi.security.keystorePasswd` will be used.
|`nifi.security.truststore` | Filename of the Truststore that will be used to authorize those connecting to NiFi. A secured instance with no Truststore will refuse all incoming connections.
|`nifi.security.truststoreType` | The type of the Truststore. Must be `PKCS12` or `JKS` or `BCFKS`. JKS is the preferred type, BCFKS and PKCS12 files will be loaded with BouncyCastle provider.
|`nifi.security.truststoreType` | The type of the Truststore. Must be `PKCS12` or `JKS` or `BCFKS`. PKCS12 is the preferred type, BCFKS and PKCS12 files will be loaded with BouncyCastle provider.
|`nifi.security.truststorePasswd` | The password for the Truststore.
|==================================================================================================================================================
@ -316,16 +316,6 @@ Once the `nifi.security.autoreload.enabled` property is set to `true`, any valid
NOTE: Changes to any of the `nifi.security.keystore*` or `nifi.security.truststore*` properties will not be picked up by the auto-refreshing logic, which assumes the passwords and store paths will remain the same.
[[tls_generation_toolkit]]
=== TLS Generation Toolkit
In order to facilitate the secure setup of NiFi, you can use the `tls-toolkit` command line utility to automatically generate the required keystores, truststore, and relevant configuration files. This is especially useful for securing multiple NiFi nodes, which can be a tedious and error-prone process. For more information, see the <<toolkit-guide.adoc#tls_toolkit,TLS Toolkit>> section in the link:toolkit-guide.html[NiFi Toolkit Guide]. Related topics include:
* <<toolkit-guide.adoc#wildcard_certificates,Wildcard Certificates>>
* <<toolkit-guide.adoc#tls_operation_modes,Operation Modes: Standalone and Client/Server>>
* <<toolkit-guide.adoc#tls_intermediate_ca,Using An Existing Intermediate Certificate Authority>>
* <<toolkit-guide.adoc#additional_certificate_commands,Additional Certificate Commands>>
[[tls_cipher_suites]]
=== TLS Cipher Suites
@ -2261,7 +2251,7 @@ nifi.bootstrap.protection.context.mapping.ldap=ldap-.*
This would cause both of the above to be assigned a context of `"ldap/Manager Password"` instead of `"default/Manager Password"`.
[[admin-toolkit]]
== NiFi Toolkit Administrative Tools
In addition to `tls-toolkit` and `encrypt-config`, the NiFi Toolkit also contains command line utilities for administrators to support NiFi maintenance in standalone and clustered environments. These utilities include:
In addition to `encrypt-config`, the NiFi Toolkit also contains command line utilities for administrators to support NiFi maintenance in standalone and clustered environments. These utilities include:
* CLI -- The `cli` tool enables administrators to interact with NiFi and NiFi Registry instances to automate tasks such as deploying versioned flows and managing process groups and cluster nodes.
* File Manager -- The `file-manager` tool enables administrators to backup, install or restore a NiFi installation from backup.
@ -2896,7 +2886,6 @@ in the _$NIFI_HOME/conf/nifi.properties_ file:
|===
Whether using the default security properties or the ZooKeeper specific properties, the keystore and truststores must contain the appropriate keys and certificates for use with ZooKeeper (i.e., the keys and certificates need to align with the ZooKeeper configuration either way).
NiFi's TLS Toolkit can be used to help generate the keystore and truststore used for ZooKeeper client/server access.
After updating the above properties and starting NiFi, network communication with ZooKeeper will be secure and ZooKeeper will now use the NiFi node's certificate principal
when authenticating access. This will be reflected in log messages like the following on the ZooKeeper server:

21
nifi-docs/src/main/asciidoc/developer-guide.adoc
View File

@ -2203,27 +2203,6 @@ application/avro+binary
------------------------------------------------------------------------------------------------
== Command Line Tools
=== tls-toolkit
The Client/Server mode of operation came about from the desire to automatically generate required TLS configuration artifacts without needing to perform that generation in a centralized place. This simplifies configuration in a clustered environment. Since we don’t necessarily have a central place to run the generation logic or a trusted Certificate Authority, a shared secret is used to authenticate the clients and server to each other.
The tls-toolkit prevents man in the middle attacks using HMAC verification of the public keys of the CA server and the CSR the client sends. A shared secret (the token) is used as the HMAC key.
The basic process goes as follows:
1. The client generates a KeyPair.
2. The client generates a request json payload containing a CSR and an HMAC with the token as the key and the CSR’s public key fingerprint as the data.
3. The client connects to the CA Hostname at the https port specified and validates that the CN of the CA’s certificate matches the hostname (NOTE: because we don’t trust the CA at this point, this adds NO security, it is just a way to error out early if possible).
4. The server validates the HMAC from the client payload using the token as the key and the CSR’s public key fingerprint as the data. This proves that the client knows the shared secret and that it wanted a CSR with that public key to be signed. (NOTE: a man in the middle could forward this on but wouldn’t be able to change the CSR without invalidating the HMAC, defeating the purpose).
5. The server signs the CSR and sends back a response json payload containing the certificate and an HMAC with the token as the key and a fingerprint of its public key as the data.
6. The client validates the response HMAC using the token as the key and a fingerprint of the certificate public key supplied by the TLS session. This validates that a CA that knows the shared secret is the one we are talking to over TLS.
7. The client verifies that the CA certificate from the TLS session signed the certificate in the payload.
8. The client adds the generated KeyPair to its keystore with the certificate chain and adds the CA certificate from the TLS connection to its truststore.
9. The client writes out the configuration json containing keystore, truststore passwords and other details about the exchange.
== Testing
Testing the components that will be used within a larger framework can often be very cumbersome

478
nifi-docs/src/main/asciidoc/toolkit-guide.adoc
View File

@ -24,7 +24,6 @@ The NiFi Toolkit contains several command line utilities to setup and support Ni
* CLI -- The `cli` tool enables administrators to interact with NiFi and NiFi Registry instances to automate tasks such as deploying versioned flows and managing process groups and cluster nodes.
* Encrypt Config -- The `encrypt-config` tool encrypts the sensitive keys in the _nifi.properties_ file to facilitate the setup of a secure NiFi instance.
* TLS Toolkit -- The `tls-toolkit` utility generates the required keystores, truststore, and relevant configuration files to facilitate the setup of a secure NiFi instance.
The utilities are executed with scripts found in the `bin` folder of your NiFi Toolkit installation.
@ -841,480 +840,3 @@ The missing buckets, flows and versions will be created. If bucket and flow exis
2. Import versions:
./bin/cli.sh registry import-all-flows -u http://nifi-registry-2:18080 --input "/my_dir/flow_exports"
[[tls_toolkit]]
== TLS Toolkit
In order to facilitate the secure setup of NiFi, you can use the `tls-toolkit` command line utility to automatically generate the required keystores, truststore, and relevant configuration files. This is especially useful for securing multiple NiFi nodes, which can be a tedious and error-prone process.
NOTE: Please note that there are new requirements for trusted certificates in macOS 10.15. Details can be found link:https://support.apple.com/en-us/HT210176[here^], but of particular importance is that all TLS server certificates issued after July 1, 2019 must have a validity period of 825 days or less.
[[wildcard_certificates]]
=== Wildcard Certificates
Wildcard certificates (i.e. two nodes `node1.nifi.apache.org` and `node2.nifi.apache.org` being assigned the same certificate with a CN or SAN entry of `+*.nifi.apache.org+`) are *not officially supported* and *not recommended*. There are numerous disadvantages to using wildcard certificates, and a cluster working with wildcard certificates has occurred in previous versions out of lucky accidents, not intentional support. Wildcard SAN entries are acceptable *if* each cert maintains an additional unique SAN entry and CN entry.
==== Potential issues with wildcard certificates
* In many places throughout the codebase, cluster communications use certificate identities many times to identify a node, and if the certificate simply presents a wildcard DN, that doesn’t resolve to a specific node
* Admins may need to provide a custom node identity in _authorizers.xml_ for `*.nifi.apache.org` because all proxy actions only resolve to the cert DN (see the <<administration-guide.adoc#user_authentication,User Authentication>> section in the System Administrator's Guide for more information).
* Admins have no traceability into which node performed an action because they all resolve to the same DN
* Admins running multiple instances on the same machine using different ports to identify them can accidentally put `node1` hostname with `node2` port, and the address will resolve fine because it’s using the same certificate, but the host header handler will block it because the `node1` hostname is (correctly) not listed as an acceptable host for `node2` instance
* If the wildcard certificate is compromised, all nodes are compromised
NOTE: JKS keystores and truststores are recommended for NiFi. This tool allows the specification of other keystore types on the command line but will ignore a type of PKCS12 for use as the truststore because that format has some compatibility issues between BouncyCastle and Oracle implementations.
[[tls_operation_modes]]
=== Operation Modes
The `tls-toolkit` command line tool has two primary modes of operation:
1. Standalone -- generates the certificate authority, keystores, truststores, and _nifi.properties_ files in one command.
2. Client/Server -- uses a Certificate Authority Server that accepts Certificate Signing Requests from clients, signs them, and sends the resulting certificates back. Both client and server validate the other’s identity through a shared secret.
==== Standalone
Standalone mode is invoked by running `./bin/tls-toolkit.sh standalone` or `bin\tls-toolkit.sh standalone`.
===== Usage
To show help:
./bin/tls-toolkit.sh standalone -h
The following are available options:
* `-a`,`--keyAlgorithm <arg>` Algorithm to use for generated keys (default: `RSA`)
* `--additionalCACertificate <arg>` Path to additional CA certificate (used to sign toolkit CA certificate) in PEM format if necessary
* `-B`,`--clientCertPassword <arg>` Password for client certificate. Must either be one value or one for each client DN (auto-generate if not specified)
* `-c`,`--certificateAuthorityHostname <arg>` Hostname of NiFi Certificate Authority (default: `localhost`)
* `-C`,`--clientCertDn <arg>` Generate client certificate suitable for use in browser with specified DN (Can be specified multiple times)
* `-d`,`--days <arg>` Number of days issued certificate should be valid for (default: `825`)
* `-f`,`--nifiPropertiesFile <arg>` Base _nifi.properties_ file to update (Embedded file identical to the one in a default NiFi install will be used if not specified)
* `-g`,`--differentKeyAndKeystorePasswords` Use different generated password for the key and the keystore
* `-G`,`--globalPortSequence <arg>` Use sequential ports that are calculated for all hosts according to the provided hostname expressions (Can be specified multiple times, MUST BE SAME FROM RUN TO RUN)
* `-h`,`--help` Print help and exit
* `-k`,`--keySize <arg>` Number of bits for generated keys (default: `2048`)
* `-K`,`--keyPassword <arg>` Key password to use. Must either be one value or one for each host (auto-generate if not specified)
* `-n`,`--hostnames <arg>` Comma separated list of hostnames
* `--nifiDnPrefix <arg>` String to prepend to hostname(s) when determining DN (default: `CN=`)
* `--nifiDnSuffix <arg>` String to append to hostname(s) when determining DN (default: `, OU=NIFI`)
* `-o`,`--outputDirectory <arg>` The directory to output keystores, truststore, config files (default: `../bin`)
* `-O`,`--isOverwrite` Overwrite existing host output
* `-P`,`--trustStorePassword <arg>` Keystore password to use. Must either be one value or one for each host (auto-generate if not specified)
* `-s`,`--signingAlgorithm <arg>` Algorithm to use for signing certificates (default: `SHA256WITHRSA`)
* `-S`,`--keyStorePassword <arg>` Keystore password to use. Must either be one value or one for each host (auto-generate if not specified)
* `--subjectAlternativeNames <arg>` Comma-separated list of domains to use as Subject Alternative Names in the certificate
* `-T`,`--keyStoreType <arg>` The type of keystores to generate (default: `jks`)
"Hostname" and "Subject Alternative Name" Patterns:
* Square brackets can be used in order to easily specify a range of hostnames or subject alternative names. Example: `[01-20]`
* Parentheses can be used in order to specify that more than one NiFi instance will run on the given host(s). Example: `(5)`
Examples:
Create 4 sets of keystore, truststore, _nifi.properties_ for localhost along with a client certificate with the given DN:
----
bin/tls-toolkit.sh standalone -n 'localhost(4)' -C 'CN=username,OU=NIFI'
----
Create keystore, truststore, _nifi.properties_ for 10 NiFi hostnames in each of 4 subdomains:
----
bin/tls-toolkit.sh standalone -n 'nifi[01-10].subdomain[1-4].domain'
----
Create 2 sets of keystore, truststore, _nifi.properties_ for 10 NiFi hostnames in each of 4 subdomains along with a client certificate with the given DN:
----
bin/tls-toolkit.sh standalone -n 'nifi[01-10].subdomain[1-4].domain(2)' -C 'CN=username,OU=NIFI'
----
The same command with a range of subject alternate names:
----
bin/tls-toolkit.sh standalone -n 'nifi[01-10].subdomain[1-4].domain(2)' -C 'CN=username,OU=NIFI' --subjectAlternativeNames 'nifi[21-30].other[2-5].example.com(2)'
----
==== Client/Server
Client/Server mode relies on a long-running Certificate Authority (CA) to issue certificates. The CA can be stopped when you’re not bringing nodes online.
===== Server
CA server mode is invoked by running `./bin/tls-toolkit.sh server` or `bin\tls-toolkit.sh server`.
====== Usage
To show help:
./bin/tls-toolkit.sh server -h
The following are available options:
* `-a`,`--keyAlgorithm <arg>` Algorithm to use for generated keys (default: `RSA`)
* `--configJsonIn <arg>` The place to read configuration info from (defaults to the value of configJson), implies useConfigJson if set (default: `configJson` value)
* `-d`,`--days <arg>` Number of days issued certificate should be valid for (default: `825`)
* `-D`,`--dn <arg>` The dn to use for the CA certificate (default: `CN=YOUR_CA_HOSTNAME,OU=NIFI`)
* `-f`,`--configJson <arg>` The place to write configuration info (default: `config.json`)
* `-F`,`--useConfigJson` Flag specifying that all configuration is read from `configJson` to facilitate automated use (otherwise `configJson` will only be written to)
* `-g`,`--differentKeyAndKeystorePasswords` Use different generated password for the key and the keystore
* `-h`,`--help` Print help and exit
* `-k`,`--keySize <arg>` Number of bits for generated keys (default: `2048`)
* `-p`,`--PORT <arg>` The port for the Certificate Authority to listen on (default: `9443`)
* `-s`,`--signingAlgorithm <arg>` Algorithm to use for signing certificates (default: `SHA256WITHRSA`)
* `-T`,`--keyStoreType <arg>` The type of keystores to generate (default: `jks`)
* `-t`,`--token <arg>` The token to use to prevent MITM (required and must be same as one used by clients)
===== Client
The client can be used to request new Certificates from the CA. The client utility generates a keypair and Certificate Signing Request (CSR) and sends the CSR to the Certificate Authority. CA client mode is invoked by running `./bin/tls-toolkit.sh client` or `bin\tls-toolkit.sh client`.
====== Usage
To show help:
./bin/tls-toolkit.sh client -h
The following are available options:
* `-a`,`--keyAlgorithm <arg>` Algorithm to use for generated keys (default: `RSA`)
* `-c`,`--certificateAuthorityHostname <arg>` Hostname of NiFi Certificate Authority (default: `localhost`)
* `-C`,`--certificateDirectory <arg>` The directory to write the CA certificate (default: `.`)
* `--configJsonIn <arg>` The place to read configuration info from, implies `useConfigJson` if set (default: `configJson` value)
* `-D`,`--dn <arg>` The DN to use for the client certificate (default: `CN=<localhost name>,OU=NIFI`) (this is auto-populated by the tool)
* `-f`,`--configJson <arg>` The place to write configuration info (default: `config.json`)
* `-F`,`--useConfigJson` Flag specifying that all configuration is read from `configJson` to facilitate automated use (otherwise `configJson` will only be written to)
* `-g`,`--differentKeyAndKeystorePasswords` Use different generated password for the key and the keystore
* `-h`,`--help` Print help and exit
* `-k`,`--keySize <arg>` Number of bits for generated keys (default: `2048`)
* `-p`,`--PORT <arg>` The port to use to communicate with the Certificate Authority (default: `9443`)
* `--subjectAlternativeNames <arg>` Comma-separated list of domains to use as Subject Alternative Names in the certificate
* `-T`,`--keyStoreType <arg>` The type of keystores to generate (default: `jks`)
* `-t`,`--token <arg>` The token to use to prevent MITM (required and must be same as one used by CA)
After running the client you will have the CA’s certificate, a keystore, a truststore, and a `config.json` with information about them as well as their passwords.
For a client certificate that can be easily imported into the browser, specify: `-T PKCS12`.
[[tls_intermediate_ca]]
=== Using An Existing Intermediate Certificate Authority (CA)
In some enterprise scenarios, a security/IT team may provide a signing certificate that has already been signed by the organization's certificate authority (CA). This *intermediate CA* can be used to sign the *node* (sometimes referred to as *leaf*) certificates that will be installed on each NiFi node, or the *client certificates* used to identify users. In order to inject the existing signing certificate into the toolkit process, follow these steps:
. Generate or obtain the signed intermediate CA keys in the following format (see additional commands below):
* Public certificate in PEM format: `nifi-cert.pem`
* Private key in PEM format: `nifi-key.key`
. Place the files in the *toolkit working directory*. This is the directory where the tool is configured to output the signed certificates. *This is not necessarily the directory where the binary is located or invoked*.
* For example, given the following scenario, the toolkit command can be run from its location as long as the output directory `-o` is `../hardcoded/`, and the existing `nifi-cert.pem` and `nifi-key.key` will be used.
** e.g. `$ ./toolkit/bin/tls-toolkit.sh standalone -o ./hardcoded/ -n 'node4.nifi.apache.org' -P thisIsABadPassword -S thisIsABadPassword -O` will result in a new directory at `./hardcoded/node4.nifi.apache.org` with a keystore and truststore containing a certificate signed by `./hardcoded/nifi-key.key`
* If the `-o` argument is not provided, the default working directory (`.`) must contain `nifi-cert.pem` and `nifi-key.key`
** e.g. `$ cd ./hardcoded/ && ../toolkit/bin/tls-toolkit.sh standalone -n 'node5.nifi.apache.org' -P thisIsABadPassword -S thisIsABadPassword -O`
[source]
----
# Example directory structure *before* commands above are run
🔓 0s @ 18:07:58 $ tree -L 2
.
├── hardcoded
│ ├── CN=myusername.hardcoded_OU=NiFi.p12
│ ├── CN=myusername.hardcoded_OU=NiFi.password
│ ├── nifi-cert.pem
│ ├── nifi-key.key
│ ├── node1.nifi.apache.org
│ ├── node2.nifi.apache.org
│ └── node3.nifi.apache.org
└── toolkit
├── LICENSE
├── NOTICE
├── README
├── bin
├── conf
├── docs
└── lib
----
The `nifi-cert.pem` and `nifi-key.key` files should be ASCII-armored (Base64-encoded ASCII) files containing the CA public certificate and private key respectively. Here are sample files of each to show the expected format:
==== nifi-cert.pem
[source]
----
# The first command shows the actual content of the encoded file, and the second parses it and shows the internal values
.../certs $ more nifi-cert.pem
-----BEGIN CERTIFICATE-----
MIIDZTCCAk2gAwIBAgIKAWTeM3kDAAAAADANBgkqhkiG9w0BAQsFADAxMQ0wCwYD
VQQLDAROSUZJMSAwHgYDVQQDDBduaWZpLWNhLm5pZmkuYXBhY2hlLm9yZzAeFw0x
ODA3MjgwMDA0MzJaFw0yMTA3MjcwMDA0MzJaMDExDTALBgNVBAsMBE5JRkkxIDAe
BgNVBAMMF25pZmktY2EubmlmaS5hcGFjaGUub3JnMIIBIjANBgkqhkiG9w0BAQEF
AAOCAQ8AMIIBCgKCAQEAqkVrrC+AkFbjnCpupSy84tTFDsRVUIWYj/k2pVwC145M
3bpr0pRCzLuzovAjFCmT5L+isTvNjhionsqif07Ebd/M2psYE/Rih2MULsX6KgRe
1nRUiBeKF08hlmSBMGDFPj39yDzE/V9edxV/KGjRqVgw/Qy0vwaS5uWdXnLDhzoV
4/Mz7lGmYoMasZ1uexlH93jjBl1+EFL2Xoa06oLbEojJ9TKaWhpG8ietEedf7WM0
zqBEz2kHo9ddFk9yxiCkT4SUKnDWkhwc/o6us1vEXoSw+tmufHY/A3gVihjWPIGz
qyLFl9JuN7CyJepkVVqTdskBG7S85G/kBlizUj5jOwIDAQABo38wfTAOBgNVHQ8B
Af8EBAMCAf4wDAYDVR0TBAUwAwEB/zAdBgNVHQ4EFgQUKiWBKbMMQ1zUabD4gI7L
VOWOcy0wHwYDVR0jBBgwFoAUKiWBKbMMQ1zUabD4gI7LVOWOcy0wHQYDVR0lBBYw
FAYIKwYBBQUHAwIGCCsGAQUFBwMBMA0GCSqGSIb3DQEBCwUAA4IBAQAxfHFIZLOw
mwIqnSI/ir8f/uzDMq06APHGdhdeIKV0HR74BtK95KFg42zeXxAEFeic98PC/FPV
tKpm2WUa1slMB+oP27cRx5Znr2+pktaqnM7f2JgMeJ8bduNH3RUkr9jwgkcJRwyC
I4fwHC9k18aizNdOf2q2UgQXxNXaLYPe17deuNVwwrflMgeFfVrwbT2uPJTMRi1D
FQyc6haF4vsOSSRzE6OyDoc+/1PpyPW75OeSXeVCbc3AEAvRuTZMBQvBQUqVM51e
MDG+K3rCeieSBPOnGNrEC/PiA/CvaMXBEog+xPAw1SgYfuCz4rlM3BdRa54z3+oO
lc8xbzd7w8Q3
-----END CERTIFICATE-----
.../certs $ openssl x509 -in nifi-cert.pem -text -noout
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
01:64:de:33:79:03:00:00:00:00
Signature Algorithm: sha256WithRSAEncryption
Issuer: OU=NIFI, CN=nifi-ca.nifi.apache.org
Validity
Not Before: Jul 28 00:04:32 2018 GMT
Not After : Jul 27 00:04:32 2021 GMT
Subject: OU=NIFI, CN=nifi-ca.nifi.apache.org
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:aa:45:6b:ac:2f:80:90:56:e3:9c:2a:6e:a5:2c:
bc:e2:d4:c5:0e:c4:55:50:85:98:8f:f9:36:a5:5c:
02:d7:8e:4c:dd:ba:6b:d2:94:42:cc:bb:b3:a2:f0:
23:14:29:93:e4:bf:a2:b1:3b:cd:8e:18:a8:9e:ca:
a2:7f:4e:c4:6d:df:cc:da:9b:18:13:f4:62:87:63:
14:2e:c5:fa:2a:04:5e:d6:74:54:88:17:8a:17:4f:
21:96:64:81:30:60:c5:3e:3d:fd:c8:3c:c4:fd:5f:
5e:77:15:7f:28:68:d1:a9:58:30:fd:0c:b4:bf:06:
92:e6:e5:9d:5e:72:c3:87:3a:15:e3:f3:33:ee:51:
a6:62:83:1a:b1:9d:6e:7b:19:47:f7:78:e3:06:5d:
7e:10:52:f6:5e:86:b4:ea:82:db:12:88:c9:f5:32:
9a:5a:1a:46:f2:27:ad:11:e7:5f:ed:63:34:ce:a0:
44:cf:69:07:a3:d7:5d:16:4f:72:c6:20:a4:4f:84:
94:2a:70:d6:92:1c:1c:fe:8e:ae:b3:5b:c4:5e:84:
b0:fa:d9:ae:7c:76:3f:03:78:15:8a:18:d6:3c:81:
b3:ab:22:c5:97:d2:6e:37:b0:b2:25:ea:64:55:5a:
93:76:c9:01:1b:b4:bc:e4:6f:e4:06:58:b3:52:3e:
63:3b
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Key Usage: critical
Digital Signature, Non Repudiation, Key Encipherment, Data Encipherment, Key Agreement, Certificate Sign, CRL Sign
X509v3 Basic Constraints:
CA:TRUE
X509v3 Subject Key Identifier:
2A:25:81:29:B3:0C:43:5C:D4:69:B0:F8:80:8E:CB:54:E5:8E:73:2D
X509v3 Authority Key Identifier:
keyid:2A:25:81:29:B3:0C:43:5C:D4:69:B0:F8:80:8E:CB:54:E5:8E:73:2D
X509v3 Extended Key Usage:
TLS Web Client Authentication, TLS Web Server Authentication
Signature Algorithm: sha256WithRSAEncryption
31:7c:71:48:64:b3:b0:9b:02:2a:9d:22:3f:8a:bf:1f:fe:ec:
c3:32:ad:3a:00:f1:c6:76:17:5e:20:a5:74:1d:1e:f8:06:d2:
bd:e4:a1:60:e3:6c:de:5f:10:04:15:e8:9c:f7:c3:c2:fc:53:
d5:b4:aa:66:d9:65:1a:d6:c9:4c:07:ea:0f:db:b7:11:c7:96:
67:af:6f:a9:92:d6:aa:9c:ce:df:d8:98:0c:78:9f:1b:76:e3:
47:dd:15:24:af:d8:f0:82:47:09:47:0c:82:23:87:f0:1c:2f:
64:d7:c6:a2:cc:d7:4e:7f:6a:b6:52:04:17:c4:d5:da:2d:83:
de:d7:b7:5e:b8:d5:70:c2:b7:e5:32:07:85:7d:5a:f0:6d:3d:
ae:3c:94:cc:46:2d:43:15:0c:9c:ea:16:85:e2:fb:0e:49:24:
73:13:a3:b2:0e:87:3e:ff:53:e9:c8:f5:bb:e4:e7:92:5d:e5:
42:6d:cd:c0:10:0b:d1:b9:36:4c:05:0b:c1:41:4a:95:33:9d:
5e:30:31:be:2b:7a:c2:7a:27:92:04:f3:a7:18:da:c4:0b:f3:
e2:03:f0:af:68:c5:c1:12:88:3e:c4:f0:30:d5:28:18:7e:e0:
b3:e2:b9:4c:dc:17:51:6b:9e:33:df:ea:0e:95:cf:31:6f:37:
7b:c3:c4:37
----
==== nifi-key.key
[source]
----
# The first command shows the actual content of the encoded file, and the second parses it and shows the internal values
.../certs $ more nifi-key.key
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAqkVrrC+AkFbjnCpupSy84tTFDsRVUIWYj/k2pVwC145M3bpr
0pRCzLuzovAjFCmT5L+isTvNjhionsqif07Ebd/M2psYE/Rih2MULsX6KgRe1nRU
iBeKF08hlmSBMGDFPj39yDzE/V9edxV/KGjRqVgw/Qy0vwaS5uWdXnLDhzoV4/Mz
7lGmYoMasZ1uexlH93jjBl1+EFL2Xoa06oLbEojJ9TKaWhpG8ietEedf7WM0zqBE
z2kHo9ddFk9yxiCkT4SUKnDWkhwc/o6us1vEXoSw+tmufHY/A3gVihjWPIGzqyLF
l9JuN7CyJepkVVqTdskBG7S85G/kBlizUj5jOwIDAQABAoIBAAdWRnV89oVBuT0Z
dvsXGmyLzpH8U9DMcO6DRp+Jf3XaY+WKCutgCCDaVbtHrbtIr17EAzav5QOifGGb
SbVCp6Q0aJdi5360oSpEUrJRRZ5Z4dxL1vimSwUGG+RnIEn9YYJ1GWJve+2PFnr7
KieLnL03V6UPzxoMJnhcnJNdTp+dBwzSazVQwye2csSJlVMk49t2lxBwce7ohuh+
9fL7G3HU5S9d08QT1brknMHahcw1SYyJd0KSjRJCB6wAxnAZmJYJ1jQCI8YICq0j
RX2rhxEXuEMXQcaiFQXzCrmQEXreKUISDvNeu/h7YU9UvJWPZSFGnEGgnMP2XvQm
EjK3rQECgYEA5+OkpLsiLNMHGzj72PiBkq82sTLQJ2+8udYp6PheOGkhjjXoBse5
YynyHlQt6CnVpJQ33mQUkJ+3ils0SMFtmI3rz3udzleek1so2L2J3+CI4kt7fFCb
FFbVXv+dLNrm+tOw68J48asyad8kEnHYq9Us+/3MLDmFJYTthkgzCpECgYEAu/ml
lQaWaZAQcQ8UuVeasxMYoN8zMmzfrkxc8AfNwKxF9nc44ywo4nJr+u/UVRGYpRgM
rdll5vz0Iq68qk03spaW7vDJn8hJQhkReQw1it9Fp/51r9MHzGTVarORJGa2oZ0g
iNe8LNizD3bQ19hEvju9mn0x9Q62Q7dapVpffwsCgYEAtC1TPpQQ59dIjERom5vr
wffWfTTIO/w8HgFkKxrgyuAVLJSCJtKFH6H1+M7bpKrsz6ZDCs+kkwMm76ASLf3t
lD2h3mNkqHG4SzLnuBD90jB666pO1rci6FjYDap7i+DC3F4j9+vxYYXt9Aln09UV
z94hx+LaA/rlk9OHY3EyB6ECgYBA/cCtNNjeaKv2mxM8PbjD/289d85YueHgfpCH
gPs3iZiq7W+iw8ri+FKzMSaFvw66zgTcOtULtxulviqG6ym9umk29dOQRgxmKQqs
gnckq6uGuOjxwJHqrlZHjQw6vLSaThxIk+aAzu+iAh+U8TZbW4ZjmrOiGdMUuJlD
oGpyHwKBgQCRjfqQjRelYVtU7j6BD9BDbCfmipwaRNP0CuAGOVtS+UnJuaIhsXFQ
QGEBuOnfFijIvb7YcXRL4plRYPMvDqYRNObuI6A+1xNtr000nxa/HUfzKVeI9Tsn
9AKMWnXS8ZcfStsVf3oDFffXYRqCaWeuhpMmg9TwdXoAuwfpE5GCmw==
-----END RSA PRIVATE KEY-----
.../certs $ openssl rsa -in nifi-key.key -text -noout
Private-Key: (2048 bit)
modulus:
00:aa:45:6b:ac:2f:80:90:56:e3:9c:2a:6e:a5:2c:
bc:e2:d4:c5:0e:c4:55:50:85:98:8f:f9:36:a5:5c:
02:d7:8e:4c:dd:ba:6b:d2:94:42:cc:bb:b3:a2:f0:
23:14:29:93:e4:bf:a2:b1:3b:cd:8e:18:a8:9e:ca:
a2:7f:4e:c4:6d:df:cc:da:9b:18:13:f4:62:87:63:
14:2e:c5:fa:2a:04:5e:d6:74:54:88:17:8a:17:4f:
21:96:64:81:30:60:c5:3e:3d:fd:c8:3c:c4:fd:5f:
5e:77:15:7f:28:68:d1:a9:58:30:fd:0c:b4:bf:06:
92:e6:e5:9d:5e:72:c3:87:3a:15:e3:f3:33:ee:51:
a6:62:83:1a:b1:9d:6e:7b:19:47:f7:78:e3:06:5d:
7e:10:52:f6:5e:86:b4:ea:82:db:12:88:c9:f5:32:
9a:5a:1a:46:f2:27:ad:11:e7:5f:ed:63:34:ce:a0:
44:cf:69:07:a3:d7:5d:16:4f:72:c6:20:a4:4f:84:
94:2a:70:d6:92:1c:1c:fe:8e:ae:b3:5b:c4:5e:84:
b0:fa:d9:ae:7c:76:3f:03:78:15:8a:18:d6:3c:81:
b3:ab:22:c5:97:d2:6e:37:b0:b2:25:ea:64:55:5a:
93:76:c9:01:1b:b4:bc:e4:6f:e4:06:58:b3:52:3e:
63:3b
publicExponent: 65537 (0x10001)
privateExponent:
07:56:46:75:7c:f6:85:41:b9:3d:19:76:fb:17:1a:
6c:8b:ce:91:fc:53:d0:cc:70:ee:83:46:9f:89:7f:
75:da:63:e5:8a:0a:eb:60:08:20:da:55:bb:47:ad:
bb:48:af:5e:c4:03:36:af:e5:03:a2:7c:61:9b:49:
b5:42:a7:a4:34:68:97:62:e7:7e:b4:a1:2a:44:52:
b2:51:45:9e:59:e1:dc:4b:d6:f8:a6:4b:05:06:1b:
e4:67:20:49:fd:61:82:75:19:62:6f:7b:ed:8f:16:
7a:fb:2a:27:8b:9c:bd:37:57:a5:0f:cf:1a:0c:26:
78:5c:9c:93:5d:4e:9f:9d:07:0c:d2:6b:35:50:c3:
27:b6:72:c4:89:95:53:24:e3:db:76:97:10:70:71:
ee:e8:86:e8:7e:f5:f2:fb:1b:71:d4:e5:2f:5d:d3:
c4:13:d5:ba:e4:9c:c1:da:85:cc:35:49:8c:89:77:
42:92:8d:12:42:07:ac:00:c6:70:19:98:96:09:d6:
34:02:23:c6:08:0a:ad:23:45:7d:ab:87:11:17:b8:
43:17:41:c6:a2:15:05:f3:0a:b9:90:11:7a:de:29:
42:12:0e:f3:5e:bb:f8:7b:61:4f:54:bc:95:8f:65:
21:46:9c:41:a0:9c:c3:f6:5e:f4:26:12:32:b7:ad:
01
prime1:
00:e7:e3:a4:a4:bb:22:2c:d3:07:1b:38:fb:d8:f8:
81:92:af:36:b1:32:d0:27:6f:bc:b9:d6:29:e8:f8:
5e:38:69:21:8e:35:e8:06:c7:b9:63:29:f2:1e:54:
2d:e8:29:d5:a4:94:37:de:64:14:90:9f:b7:8a:5b:
34:48:c1:6d:98:8d:eb:cf:7b:9d:ce:57:9e:93:5b:
28:d8:bd:89:df:e0:88:e2:4b:7b:7c:50:9b:14:56:
d5:5e:ff:9d:2c:da:e6:fa:d3:b0:eb:c2:78:f1:ab:
32:69:df:24:12:71:d8:ab:d5:2c:fb:fd:cc:2c:39:
85:25:84:ed:86:48:33:0a:91
prime2:
00:bb:f9:a5:95:06:96:69:90:10:71:0f:14:b9:57:
9a:b3:13:18:a0:df:33:32:6c:df:ae:4c:5c:f0:07:
cd:c0:ac:45:f6:77:38:e3:2c:28:e2:72:6b:fa:ef:
d4:55:11:98:a5:18:0c:ad:d9:65:e6:fc:f4:22:ae:
bc:aa:4d:37:b2:96:96:ee:f0:c9:9f:c8:49:42:19:
11:79:0c:35:8a:df:45:a7:fe:75:af:d3:07:cc:64:
d5:6a:b3:91:24:66:b6:a1:9d:20:88:d7:bc:2c:d8:
b3:0f:76:d0:d7:d8:44:be:3b:bd:9a:7d:31:f5:0e:
b6:43:b7:5a:a5:5a:5f:7f:0b
exponent1:
00:b4:2d:53:3e:94:10:e7:d7:48:8c:44:68:9b:9b:
eb:c1:f7:d6:7d:34:c8:3b:fc:3c:1e:01:64:2b:1a:
e0:ca:e0:15:2c:94:82:26:d2:85:1f:a1:f5:f8:ce:
db:a4:aa:ec:cf:a6:43:0a:cf:a4:93:03:26:ef:a0:
12:2d:fd:ed:94:3d:a1:de:63:64:a8:71:b8:4b:32:
e7:b8:10:fd:d2:30:7a:eb:aa:4e:d6:b7:22:e8:58:
d8:0d:aa:7b:8b:e0:c2:dc:5e:23:f7:eb:f1:61:85:
ed:f4:09:67:d3:d5:15:cf:de:21:c7:e2:da:03:fa:
e5:93:d3:87:63:71:32:07:a1
exponent2:
40:fd:c0:ad:34:d8:de:68:ab:f6:9b:13:3c:3d:b8:
c3:ff:6f:3d:77:ce:58:b9:e1:e0:7e:90:87:80:fb:
37:89:98:aa:ed:6f:a2:c3:ca:e2:f8:52:b3:31:26:
85:bf:0e:ba:ce:04:dc:3a:d5:0b:b7:1b:a5:be:2a:
86:eb:29:bd:ba:69:36:f5:d3:90:46:0c:66:29:0a:
ac:82:77:24:ab:ab:86:b8:e8:f1:c0:91:ea:ae:56:
47:8d:0c:3a:bc:b4:9a:4e:1c:48:93:e6:80:ce:ef:
a2:02:1f:94:f1:36:5b:5b:86:63:9a:b3:a2:19:d3:
14:b8:99:43:a0:6a:72:1f
coefficient:
00:91:8d:fa:90:8d:17:a5:61:5b:54:ee:3e:81:0f:
d0:43:6c:27:e6:8a:9c:1a:44:d3:f4:0a:e0:06:39:
5b:52:f9:49:c9:b9:a2:21:b1:71:50:40:61:01:b8:
e9:df:16:28:c8:bd:be:d8:71:74:4b:e2:99:51:60:
f3:2f:0e:a6:11:34:e6:ee:23:a0:3e:d7:13:6d:af:
4d:34:9f:16:bf:1d:47:f3:29:57:88:f5:3b:27:f4:
02:8c:5a:75:d2:f1:97:1f:4a:db:15:7f:7a:03:15:
f7:d7:61:1a:82:69:67:ae:86:93:26:83:d4:f0:75:
7a:00:bb:07:e9:13:91:82:9b
----
[[tls_external-signed_ca]]
==== Signing with Externally-signed CA Certificates
To sign generated certificates with a certificate authority (CA) generated outside of the TLS Toolkit, ensure the necessary files are in the right format and location (see <<additional_certificate_commands>>). For example, an organization *Large Organization* has an internal CA (`CN=ca.large.org, OU=Certificate Authority`). This *root CA* is offline and only used to sign other internal CAs. The Large IT team generates an *intermediate CA* (`CN=nifi_ca.large.org, OU=NiFi, OU=Certificate Authority`) to be used to sign all NiFi node certificates (`CN=node1.nifi.large.org, OU=NiFi`, `CN=node2.nifi.large.org, OU=NiFi`, etc.).
To use the toolkit to generate these certificates and sign them using the *intermediate CA*, ensure that the following files are present (see <<additional_certificate_commands>>):
* `nifi-cert.pem` -- the public certificate of the *intermediate CA* in PEM format
* `nifi-key.key` -- the Base64-encoded private key of the *intermediate CA* in PKCS #1 PEM format
If the *intermediate CA* was the *root CA*, it would be *self-signed* -- the signature over the certificate would be issued from the same key. In that case (the same as a toolkit-generated CA), no additional arguments are necessary. However, because the *intermediate CA* is signed by the *root CA*, the public certificate of the *root CA* needs to be provided as well to validate the signature. The `--additionalCACertificate` parameter is used to specify the path to the signing public certificate. The value should be the absolute path to the *root CA* public certificate.
Example:
----
# Generate cert signed by intermediate CA (which is signed by root CA) -- WILL FAIL
$ ./bin/tls-toolkit.sh standalone -n 'node1.nifi.apache.org' \
-P passwordpassword \
-S passwordpassword \
-o /opt/certs/externalCA \
-O
2018/08/02 18:48:11 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandaloneCommandLine: No nifiPropertiesFile specified, using embedded one.
2018/08/02 18:48:12 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Running standalone certificate generation with output directory /opt/certs/externalCA
2018/08/02 18:48:12 INFO [main] org.apache.nifi.toolkit.tls.util.TlsHelper: Verifying the certificate signature for CN=nifi_ca.large.org, OU=Certificate Authority
2018/08/02 18:48:12 INFO [main] org.apache.nifi.toolkit.tls.util.TlsHelper: Attempting to verify certificate CN=nifi_ca.large.org, OU=NiFi, OU=Certificate Authority signature with CN=nifi_ca.large.org, OU=NiFi, OU=Certificate Authority
2018/08/02 18:48:12 WARN [main] org.apache.nifi.toolkit.tls.util.TlsHelper: Certificate CN=nifi_ca.large.org, OU=NiFi, OU=Certificate Authority not signed by CN=nifi_ca.large.org, OU=NiFi, OU=Certificate Authority [certificate does not verify with supplied key]
Error generating TLS configuration. (The signing certificate was not signed by any known certificates)
# Provide additional CA certificate path for signature verification of intermediate CA
$ ./bin/tls-toolkit.sh standalone -n 'node1.nifi.apache.org' \
-P passwordpassword \
-S passwordpassword \
-o /opt/certs/externalCA \
--additionalCACertificate /opt/certs/externalCA/root.pem \
-O
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandaloneCommandLine: No nifiPropertiesFile specified, using embedded one.
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Running standalone certificate generation with output directory /opt/certs/externalCA
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.util.TlsHelper: Verifying the certificate signature for CN=nifi_ca.large.org, OU=NiFi, OU=Certificate Authority
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.util.TlsHelper: Attempting to verify certificate CN=nifi_ca.large.org, OU=NiFi, OU=Certificate Authority signature with CN=ca.large.org, OU=Certificate Authority
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.util.TlsHelper: Certificate was signed by CN=ca.large.org, OU=Certificate Authority
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Using existing CA certificate /opt/certs/externalCA/nifi-cert.pem and key /opt/certs/externalCA/nifi-key.key
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Writing new ssl configuration to /opt/certs/externalCA/node1.nifi.apache.org
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Successfully generated TLS configuration for node1.nifi.apache.org 1 in /opt/certs/externalCA/node1.nifi.apache.org
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: No clientCertDn specified, not generating any client certificates.
2018/08/02 18:48:44 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: tls-toolkit standalone completed successfully
----
[[additional_certificate_commands]]
=== Additional Certificate Commands
. To convert from DER encoded public certificate (`cert.der`) to PEM encoded (`cert.pem`):
* If the DER file contains both the public certificate and private key, remove the private key with this command:
** `perl -pe 'BEGIN{undef $/;} s|-----BEGIN PRIVATE KEY-----.*?-----END PRIVATE KEY-----|Removed private key|gs' cert.der > cert.pem`
* If the DER file only contains the public certificate, use this command:
** `openssl x509 -inform der -in cert.der -out cert.pem`
. To convert from a PKCS12 keystore (`keystore.p12`) containing both the public certificate and private key into PEM encoded files (`$PASSWORD` is the keystore password):
* `openssl pkcs12 -in keystore.p12 -nodes -clcerts -nokeys -out cert.pem -password "pass:$PASSWORD"`
* `openssl pkcs12 -in keystore.p12 -nodes -nocerts -out key.key -password "pass:$PASSWORD"`
. To convert from a Java Keystore (`keystore.jks`) containing private key into PEM encoded files (`$P12_PASSWORD` is the PKCS12 keystore password, `$JKS_PASSWORD` is the Java keystore password you want to set, and `$ALIAS` can be any value -- the NiFi default is `nifi-key`):
* `keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12 -srcstoretype JKS -deststoretype PKCS12 -destkeypass "$P12_PASSWORD" -deststorepass "$P12_PASSWORD" -srcstorepass "$JKS_PASSWORD" -srcalias "$ALIAS" -destalias "$ALIAS"`
* Follow the steps above to convert from `keystore.p12` to `cert.pem` and `key.key`
. To convert from PKCS #8 PEM format to PKCS #1 PEM format:
* If the private key is provided in PKCS #8 format (the file begins with `-----BEGIN PRIVATE KEY-----` rather than `-----BEGIN RSA PRIVATE KEY-----`), the following command will convert it to PKCS #1 format, move the original to `nifi-key-pkcs8.key`, and rename the PKCS #1 version as `nifi-key.key`:
** `openssl rsa -in nifi-key.key -out nifi-key-pkcs1.key && mv nifi-key.key nifi-key-pkcs8.key && mv nifi-key-pkcs1.key nifi-key.key`
. To combine a private key in PEM format (`private.key`) and public certificate in PEM format (`certificate.pem`) into PKCS12 keystore:
* The following command will create the PKCS12 keystore (`keystore.p12`) from the two independent files. A Java keystore (JKS) cannot be formed directly from the PEM files:
** `openssl pkcs12 -export -out keystore.p12 -inkey private.key -in certificate.pem`
. To convert a PKCS12 keystore (`keystore.p12`) to JKS keystore (`keystore.jks`):
* The following command will create the JKS keystore (`keystore.jks`). The `-destalias` flag is optional, as NiFi does not currently read from a specific alias in the keystore. The user will be prompted for a keystore password, which must be set and have minimum 8 characters, and a key password, which can be the same as the keystore password or different:
** `keytool -importkeystore -srckeystore keystore.p12 -srcstoretype pkcs12 -destkeystore keystore.jks
-deststoretype jks -destalias nifi-key`

542
nifi-docs/src/main/asciidoc/walkthroughs.adoc
View File

@ -219,194 +219,9 @@ Apache NiFi requires link:https://en.wikipedia.org/wiki/Transport_Layer_Security
NiFi intentionally does not allow any authentication or authorization features over plaintext HTTP. Without the confidentiality and integrity provided by TLS and the user & group access controls, any malicious entity can intercept and modify NiFi API requests, corrupt and steal data, and otherwise interfere with the NiFi instance. Because of NiFi's robust feature set, this can even lead to complete control over the host running NiFi. For more information, see link:administration-guide.html#security_configuration[Administrator's Guide: Security Configuration^].
=== Securing NiFi with TLS Toolkit
NOTE: This section assumes no enterprise IT department to provide signed certificates. For a scenario with provided certificates, see <<securing-nifi-with-provided-certificates,Securing NiFi with Provided Certificates>>.
|=======================================================================================================================
|Description | Instructions on enabling link:https://en.wikipedia.org/wiki/Transport_Layer_Security[Transport Layer Security (TLS)^] for the Apache NiFi application using the TLS Toolkit
|Purpose | Securing NiFi with TLS protects data in motion and is required to enable authentication & authorization
|Starting Point | <<starting-nifi>>
|Expected Outcome | Latest version of Apache NiFi running on host over TLS with client certificate authentication and authorization enabled and a single configured user
|Estimated Duration | 10 minutes
|=======================================================================================================================
Apache NiFi provides a toolkit (a collection of command-line tools for system administration). One of these is the TLS Toolkit, which provides a self-signed link:https://en.wikipedia.org/wiki/Certificate_authority[Certificate Authority (CA)^] and can easily issue and sign certificates in the format expected by NiFi. The toolkit can be run by a user or scripted to perform automated certificate generation. For more information, see link:toolkit-guide.html#tls_toolkit[NiFi Toolkit Guide: TLS Toolkit^].
The end result will consist of a self-signed NiFi CA (the root), a keystore and truststore containing the necessary certificates for the NiFi instance to operate, and a client certificate for a human user to access NiFi.
image::nifi-tls-toolkit-standalone-cert-diagram.png["NiFi TLS Toolkit Standalone Certificate Diagram"]
. Start in the directory where the NiFi toolkit was downloaded and unarchived. For this section, the directory `/etc/nifi-toolkit-1.11.4` will be used. This directory will be referred to as the "NiFi Toolkit home directory" and can be set explicitly (this is not done automatically by NiFi Toolkit nor is it required).
* `export NIFI_TOOLKIT_HOME="/etc/nifi-toolkit-1.11.4/"` -- Sets an environment variable (`$NIFI_TOOLKIT_HOME`) which references the installation directory (optional)
* `cd /etc/nifi-toolkit-1.11.4` -- Changes the terminal to the NiFi Toolkit home directory
* `ls -alGh` -- Lists the contents of the directory (optional)
+
image::nifi-toolkit-home-dir-listing.png["NiFi Toolkit Home directory contents"]
. Generate the certificate and key for the NiFi instance. Running this command will first generate the NiFi CA root certificate and private key, then generate and sign the certificate for the application instance, and finally generate a pre-configured `nifi.properties` file.
* `./bin/tls-toolkit.sh standalone -n "localhost"` -- Generates the signed certificate for `localhost`
+
[source]
----
nifi-toolkit-1.11.4 % ./bin/tls-toolkit.sh standalone -n "localhost"
2020/04/04 19:13:29 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandaloneCommandLine: No nifiPropertiesFile specified, using embedded one.
2020/04/04 19:13:29 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Running standalone certificate generation with output directory ../nifi-toolkit-1.11.4
2020/04/04 19:13:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Generated new CA certificate ../nifi-toolkit-1.11.4/nifi-cert.pem and key ../nifi-toolkit-1.11.4/nifi-key.key
2020/04/04 19:13:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Writing new ssl configuration to ../nifi-toolkit-1.11.4/localhost
2020/04/04 19:13:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Successfully generated TLS configuration for localhost 1 in ../nifi-toolkit-1.11.4/localhost
2020/04/04 19:13:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: No clientCertDn specified, not generating any client certificates.
2020/04/04 19:13:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: tls-toolkit standalone completed successfully
----
. The toolkit has created three files in the `localhost` directory: `keystore.jks`, `truststore.jks`, and `nifi.properties`. To see what was automatically populated in `nifi.properties`, compare it to the default file in the NiFi instance.
* `diff /etc/nifi-1.11.4/conf/nifi.properties localhost/nifi.properties` -- Compares the original configuration with the newly-generated one
+
--
[source]
----
nifi-toolkit-1.11.4 % diff ../nifi-1.11.4/conf/nifi.properties localhost/nifi.properties
135,137c135,137
< nifi.remote.input.host=
< nifi.remote.input.secure=false
< nifi.remote.input.socket.port=
---
> nifi.remote.input.host=localhost
> nifi.remote.input.secure=true
> nifi.remote.input.socket.port=10443
145c145
< nifi.web.http.port=8080
---
> nifi.web.http.port=
147,148c147,148
< nifi.web.https.host=
< nifi.web.https.port=
---
> nifi.web.https.host=localhost
> nifi.web.https.port=9443
163,169c163,169
< nifi.security.keystore=
< nifi.security.keystoreType=
< nifi.security.keystorePasswd=
< nifi.security.keyPasswd=
< nifi.security.truststore=
< nifi.security.truststoreType=
< nifi.security.truststorePasswd=
---
> nifi.security.keystore=./conf/keystore.jks
> nifi.security.keystoreType=jks
> nifi.security.keystorePasswd=aCeVndQ8JxIi9kLoz9YS65RClHPxB516tmIA/n26b54
> nifi.security.keyPasswd=aCeVndQ8JxIi9kLoz9YS65RClHPxB516tmIA/n26b54
> nifi.security.truststore=./conf/truststore.jks
> nifi.security.truststoreType=jks
> nifi.security.truststorePasswd=hbuVighksEPIxl6iGl1WFCIrFqdb65KZuamj72J7Yp8
213c213
< nifi.cluster.protocol.is.secure=false
---
> nifi.cluster.protocol.is.secure=true
217,218c217,218
< nifi.cluster.node.address=
< nifi.cluster.node.protocol.port=
---
> nifi.cluster.node.address=localhost
> nifi.cluster.node.protocol.port=11443
----
The `nifi.remote` section configures link:user-guide.html#site-to-site[Site to Site^] connections. The `nifi.web` section disables the plaintext HTTP connector and enables an HTTPS connector at `localhost:9443` (the default HTTPS port for NiFi). The `nifi.security` section populates the paths to the keystore and truststore and randomly-generated passwords for each. The `nifi.cluster` section configures the link:administration-guide.html#clustering[cluster communication protocol^] (not used in a standalone instance).
--
. Copy the contents of the `localhost` directory to the `conf/` directory in the location of the NiFi installation. **This command will overwrite any existing `nifi.properties` file or keystore/truststore present in the destination.**
* `cp -rv ./localhost/* /etc/nifi-1.11.4/conf/.` -- Copies the generated files into the NiFi instance
. Generate the user's client certificate to authenticate to NiFi. The toolkit will create the certificate and sign it with the same NiFi CA certificate used for the NiFi server certificate. Because the NiFi truststore includes this public certificate, it will trust the client certificate and allow it to authenticate.
* `./bin/tls-toolkit.sh standalone -C "CN=my_username, OU=NiFi"` -- Generates and signs the client certificate
+
[source]
----
nifi-toolkit-1.11.4 % ./bin/tls-toolkit.sh standalone -C "CN=my_username, OU=NiFi"
2020/04/04 19:38:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandaloneCommandLine: No nifiPropertiesFile specified, using embedded one.
2020/04/04 19:38:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Running standalone certificate generation with output directory ../nifi-toolkit-1.11.4
2020/04/04 19:38:30 INFO [main] org.apache.nifi.toolkit.tls.util.TlsHelper: Verifying the certificate signature for CN=localhost,OU=NIFI
2020/04/04 19:38:30 INFO [main] org.apache.nifi.toolkit.tls.util.TlsHelper: Attempting to verify certificate CN=localhost,OU=NIFI signature with CN=localhost,OU=NIFI
2020/04/04 19:38:30 INFO [main] org.apache.nifi.toolkit.tls.util.TlsHelper: Certificate was signed by CN=localhost,OU=NIFI
2020/04/04 19:38:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Using existing CA certificate ../nifi-toolkit-1.11.4/nifi-cert.pem and key ../nifi-toolkit-1.11.4/nifi-key.key
2020/04/04 19:38:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: No hostnames specified, not generating any host certificates or configuration.
2020/04/04 19:38:30 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Generating new client certificate ../nifi-toolkit-1.11.4/CN=my_username_OU=NiFi.p12
2020/04/04 19:38:31 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: Successfully generated client certificate ../nifi-toolkit-1.11.4/CN=my_username_OU=NiFi.p12
2020/04/04 19:38:31 INFO [main] org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone: tls-toolkit standalone completed successfully
----
[[load-client-certificate-to-browser]]
[start=6]
. Load the client certificate into the web browser. Some browsers (e.g. Mozilla Firefox) maintain their own internal keychain separate from the operating system's (OS). Others (e.g. Apple Safari, Google Chrome) rely on the OS keychain. On most modern OS, double-clicking the PKCS12 keystore (`CN=my_username_OU=NiFi.p12`) will open it with the default handler and load it into the OS keychain. The randomly-generated password is available in `CN=my_username_OU=NiFi.password`.
. Populate the *Initial Admin Identity* in NiFi. This is the identity that will be allowed to access the NiFi instance and configure user and group access via the UI or API.
* `$EDITOR /etc/nifi-1.11.4/conf/authorizers.xml` -- Opens the `authorizers.xml` file in the text editor.
* Replace `<property name="Initial User Identity 1"></property>` in the `userGroupProvider` section with `<property name="Initial User Identity 1">CN=my_username, OU=NiFi</property>` containing the full Distinguished Name (DN) as provided to the TLS Toolkit in the previous step
* Replace `<property name="Initial Admin Identity"></property>` in the `accessPolicyProvider` section with `<property name="Initial Admin Identity">CN=my_username, OU=NiFi</property>` containing the full Distinguished Name (DN) as provided to the TLS Toolkit in the previous step
+
WARNING: This is a frequent problem area when configuring security for NiFi. The DN must match *exactly* to be authenticated. Check capitalization and whitespace especially.
. Start NiFi with the new configuration.
* `cd /etc/nifi-1.11.4/` -- Changes to the NiFi home directory
* `./bin/nifi.sh start` -- Starts NiFi
* `tail -f logs/nifi-app.log` -- Tails the application log
+
--
Note that there are now log entries about the keystore and truststore being loaded and the available URLs are HTTPS.
[source]
----
2020-04-04 19:52:01,122 INFO [main] o.e.jetty.server.handler.ContextHandler Started o.e.j.w.WebAppContext@623ebac7{nifi-error,/,file:///Users/alopresto/Workspace/scratch/release_verification/nifi-1.11.4-bin/nifi-1.11.4/work/jetty/nifi-web-error-1.11.4.war/webapp/,AVAILABLE}{./work/nar/framework/nifi-framework-nar-1.11.4.nar-unpacked/NAR-INF/bundled-dependencies/nifi-web-error-1.11.4.war}
2020-04-04 19:52:01,155 INFO [main] o.e.jetty.util.ssl.SslContextFactory x509=X509@b96fb73(nifi-key,h=[localhost],w=[]) for SslContextFactory@5edd911f[provider=null,keyStore=file:///Users/alopresto/Workspace/scratch/release_verification/nifi-1.11.4-bin/nifi-1.11.4/conf/keystore.jks,trustStore=file:///Users/alopresto/Workspace/scratch/release_verification/nifi-1.11.4-bin/nifi-1.11.4/conf/truststore.jks]
2020-04-04 19:52:01,191 INFO [main] o.eclipse.jetty.server.AbstractConnector Started ServerConnector@767191b1{SSL,[ssl, http/1.1]}{localhost:9443}
2020-04-04 19:52:01,192 INFO [main] org.eclipse.jetty.server.Server Started @24336ms
2020-04-04 19:52:01,215 INFO [main] org.apache.nifi.nar.NarAutoLoader Starting NAR Auto-Loader for directory ./extensions ...
2020-04-04 19:52:01,216 INFO [main] org.apache.nifi.nar.NarAutoLoader NAR Auto-Loader started
2020-04-04 19:52:01,216 INFO [main] org.apache.nifi.web.server.JettyServer NiFi has started. The UI is available at the following URLs:
2020-04-04 19:52:01,216 INFO [main] org.apache.nifi.web.server.JettyServer https://localhost:9443/nifi
2020-04-04 19:52:01,218 INFO [main] org.apache.nifi.BootstrapListener Successfully initiated communication with Bootstrap
2020-04-04 19:52:01,219 INFO [main] org.apache.nifi.NiFi Controller initialization took 16457023826 nanoseconds (16 seconds).
----
--
. Open the web browser to link:https://localhost:9443/nifi[`https://localhost:9443/nifi`^]. The browser will present a warning that the site you are attempting to visit is insecure because the NiFi certificate is not signed by a trusted CA. Make an exception and acknowledge the risk (all communications are still encrypted even if the browser does not recognize the certificate). The browser may prompt to select the client certificate you wish to present to NiFi. Choose the entry for `CN=my_username` generated by the toolkit.
+
--
The browser warning of an insecure server certificate
image::browser-warning-insecure-site.png["Browser warning on untrusted server TLS certificate"]
The browser prompting for a client certificate to present
image::browser-present-client-cert.png["Browser prompting for client certificate to present"]
The application running. Note the user's DN in the top-right corner
image::nifi-running-tls-client-certificate.png["NiFi running with user logged in by client certificate]
--
==== Additional Notes
* While it is recommended to configure NiFi with security immediately, some admins have already run NiFi with other configuration modifications before securing it. The TLS Toolkit provides an option to consume an existing `nifi.properties` file and make the security changes to it rather than using a default template. Use `-f /etc/nifi-1.11.4/conf/nifi.properties` or `--nifiPropertiesFile /etc/nifi-1.11.4/conf/nifi.properties` if this file already exists. For more toolkit options, see link:toolkit-guide.html#tls_operation_modes[NiFi Toolkit Guide: TLS Toolkit Operation Modes^].
* To generate a certificate for a hostname other than `localhost`, use the `-n somehost.com` argument. To run on the local machine, DNS settings must allow for this. Either modify the `/etc/hosts` file or use a tool like link:https://en.wikipedia.org/wiki/Dnsmasq[dnsmasq^] to set up custom DNS routing. This is beyond the scope of this document.
* The browser will warn about an insecure connection because it does not trust the self-signed CA certificate. To explicitly mark this certificate as trusted, follow the instructions for the relevant OS and browser combination. For example, using macOS Catalina and Google Chrome:
+
--
. Open the NiFi CA cert in the Keychain Access app. Double-click on `nifi-cert.pem` or run the following command:
* `open /etc/nifi-toolkit-1.11.4/nifi-cert.pem` -- Opens the certificate in Keychain Access
* Right-click the `localhost` certificate and select *Get Info*
image::keychain-access-certificate-listing.png["Keychain Access listing certificates"]
* Expand the *Trust* section in the dialog
* Change *Secure Sockets Layer (SSL)* to *Always Trust*
image::keychain-access-trust-certificate.png["Trusting the CA certificate for TLS/SSL"]
* Close the dialog
* Restart the browser
* Navigate to link:https://localhost:9443/nifi[`https://localhost:9443/nifi`^]
image::nifi-trusted-server-certificate.png["Browser showing trusted NiFi server certificate"]
--
=== Securing NiFi with Provided Certificates
NOTE: This section assumes an enterprise IT department or other mechanism to provide signed certificates. For a scenario with self-signed certificates, see <<securing-nifi-with-tls-toolkit,Securing NiFi with TLS Toolkit>>.
NOTE: This section assumes an enterprise IT department or other mechanism to provide signed certificates.
|=======================================================================================================================
|Description | Instructions on enabling link:https://en.wikipedia.org/wiki/Transport_Layer_Security[Transport Layer Security (TLS)^] for the Apache NiFi application using provided certificates
@ -546,8 +361,6 @@ The prerequisites for the scenario (issued by the IT department):
* The matching private key in PEM format (`client.key`)
* The CA certificate in PEM format (`cacert.pem`)
NOTE: For more information on converting certificates between various forms, see link:toolkit-guide.html#additional_certificate_commands[Toolkit Guide: Additional Certificate Commands^].
The end result will consist of a self-signed external CA (the root), a keystore and truststore containing the necessary certificates for the NiFi instance to operate, and a client certificate for a human user to access NiFi.
image::nifi-tls-standalone-external-certificate-diagram.png["NiFi TLS Standalone Provided Certificate Diagram"]
@ -814,17 +627,6 @@ Certificate was added to keystore
. Generate the client certificate keystore from the client certificate and key.
* `openssl pkcs12 -export -out CN=my_username.p12 -inkey client.key -in client.pem` -- Creates the PKCS12 keystore containing the client certificate and private key. This command prompts for an *export password* twice
From this point, the instructions are identical to those using the TLS Toolkit, starting at <<load-client-certificate-to-browser,Loading the client certificate in the browser>>.
==== Securing NiFi with TLS Toolkit and Provided Intermediate CA
Occasionally, an IT department will provide an intermediate CA certificate which is signed by a trusted certificate and can be used to generate server and client certificates on-demand by the NiFi admin without further intervention by the IT department. The TLS toolkit provides a mechanism to use the intermediate certificate to sign generated certificates.
The end result will consist of a self-signed external CA (the root), an intermediate CA used to sign NiFi certificates, a keystore and truststore containing the necessary certificates for the NiFi instance to operate, and a client certificate for a human user to access NiFi.
// TODO: Write
CAUTION: Develop section
== Deploying a NiFi Cluster
Apache NiFi can run in either _standalone_ or _clustered_ mode. A standalone node is often sufficient for dataflow operations, but in a production or high-volume environment, a cluster is more performant and resilient. For more information, see link:administration-guide.html#clustering[NiFi Administrator's Guide: Clustering^].
@ -936,315 +738,71 @@ PING imaginary.node.nifi (127.0.0.1): 56 data bytes
Here the `*.nifi` resolution redirects to the host machine's IP (`127.0.0.1`) which was configured via the `/etc/resolver/nifi` file.
--
=== Creating a NiFi Cluster
=== Securing NiFi with mTLS
|=======================================================================================================================
|Description | Instructions on configuring a 3 node unsecured cluster
|Purpose | A NiFi cluster can perform flow operations in parallel and provide resiliency if nodes are unavailable.
|Starting Point | <<installing-apache-nifi,Installing Apache NiFi>> or <<building-nifi-from-source,Building NiFi from Source>>
|Expected Outcome | 3 nodes of latest version of Apache NiFi in an unsecured cluster running on local machine
|Helpful Reading | <<starting-nifi,Starting NiFi>>
|Estimated Duration | 10 minutes
|=======================================================================================================================
NOTE: link:https://lists.apache.org/thread/vn1nzobtz4fh7fs461sgg8jj9zygrk0f[(recent mailing list discussion)^]
// TODO: Write
CAUTION: Needs a diagram
A secure setup of a NiFi cluster involves a set of keystores and truststores to facilitate secure communication between cluster nodes via the mTLS protocol. Each cluster node will use a keystore containing a private key and certificate used to identify itself, and a truststore with a certificate that specifies trusted remote endpoints. Commonly, the truststore will specify a single certificate authority, which can enable a trust relationship with any certificate signed by the authority.
CAUTION: Develop section
Multiple options are available to create the needed keystores and truststores:
. Copy the NiFi run directory 3x
. Configure the settings
. Start each node
* kubernetes / cert-manager link:https://cert-manager.io/[(link)^]
* Let's Encrypt link:https://letsencrypt.org/[(link)^]
* organization-specific Certificate Authorities
* mkcert link:https://github.com/FiloSottile/mkcert/[(link)^]
=== Creating and Securing a NiFi Cluster with the TLS Toolkit
In the special case of a single node NiFi development instance, automatic self-signed certificate generation has been available in NiFi since version 1.14.0. This utility performs the needed certificate generation and configuration on the first run of a freshly built NiFi assembly.
NOTE: This section assumes no enterprise IT department to provide signed certificates. For a scenario with provided certificates, see <<securing-nifi-with-provided-certificates,Securing NiFi with Provided Certificates>>.
[[manual-keystore]]
==== Manual Keystore Generation
Manual use of link:https://www.openssl.org/[openssl^] and/or the Java `keytool` utility can also help to provide the keystores and truststores to secure NiFi cluster communications. While use of one of the previously mentioned alternatives is encouraged, these commands are documented for informational purposes, and as an additional alternative if needed.
|=======================================================================================================================
|Description | Instructions on configuring and securing a 3 node cluster
|Purpose | A NiFi cluster can perform flow operations in parallel and provide resiliency if nodes are unavailable.
|Starting Point | <<installing-apache-nifi,Installing Apache NiFi>> or <<building-nifi-from-source,Building NiFi from Source>>
|Expected Outcome | 3 nodes of latest version of Apache NiFi in secured cluster running on local machine
|Helpful Reading | <<securing-nifi-with-tls-toolkit,Securing NiFi with TLS Toolkit>>, <<creating-a-nifi-cluster,Creating a NiFi Cluster>>, <<configuring-a-host-to-resolve-arbitrary-dns-hostnames,Configuring a Host to Resolve Arbitrary DNS Hostnames>>
|Estimated Duration | 15 minutes
|=======================================================================================================================
NOTE: The following OpenSSL version is known to support generation of certificates with "subjectAltName": `OpenSSL 3.0.7 1 Nov 2022`. The following OpenSSL version is known not to support generation of certificates with "subjectAltName": `LibreSSL 2.8.3`.
Similar to a standalone instance, a NiFi cluster must have TLS configured to enable authentication and authorization mechanisms. However, the cluster communication protocol used by NiFi and the framework authentication and authorization must also be configured to allow nodes to communicate.
NOTE: In the below instructions, values for `subjectAltName IP` and `subjectAltName DNS` should be substituted as appropriate for the use case. The instructions intend only to convey syntax.
For this guide, the three nodes will be referred to as `node1`, `node2`, and `node3`. Each will have a `$NIFI_HOME` environment variable which points to the respective "NiFi home directory".
NOTE: Many of the below commands will request a password that will protect the data generated by the command. Choose a password appropriately strong for the use case. Protect the security of the passwords and generated files in a manner appropriate for the use case.
Prerequisites:
. Generate certificate authority key.
- `openssl genrsa -aes256 -out ca.key 3072`
* DNS configuration for three hosts using the addresses `node1.nifi`, `node2.nifi`, `node3.nifi`
** This can be all side-by-side on the same physical host, using virtual machines, or using independent physical machines
* Ports open to allow the nodes to communicate
** If these machines are subject to a firewall, ensure that the following ports are open:
*** `2181`, `2888`, `3888` -- ZooKeeper ports
*** `6342` -- Load-balancing port
*** `9443` -- HTTPS port for NiFi UI/API
*** `10443` -- Site to site port
*** `11443` -- Cluster communications port
** If all the nodes will run on the same machine, the port scheme will end in the respective node identifier to avoid conflicts (e.g. HTTPS port `9441` for `node1`, `9442` for `node2`, `9443` for `node3`). Ensure that the following ports are open:
*** `2181, 2182, 2183` -- ZooKeeper ports (client port)
*** `2881, 2882, 2883` -- ZooKeeper ports (node connection port)
*** `3881, 3882, 3883` -- ZooKeeper ports (leader election port)
*** `6341, 6342, 6343` -- Load-balancing port
*** `9441, 9442, 9443` -- HTTPS port for NiFi UI/API
*** `10441, 10442, 10443` -- Site to site port
*** `11441, 11442, 11443` -- Cluster communications port
. Generate cluster node key (one for each node).
- `openssl genrsa -aes256 -out nifi1.key 3072`
- `openssl genrsa -aes256 -out nifi2.key 3072`
- ...
The end result will consist of a self-signed external CA (the root), a keystore and truststore containing the necessary certificates for each NiFi node to operate, and a client certificate for a human user to access NiFi.
. Generate certificate authority certificate.
- `openssl req -new -x509 -days 1461 -key ca.key -sha256 -out ca.cer -subj "/CN=nifi-ca/OU=nifi/"`
image::nifi-cluster-tls-toolkit-certificate-diagram.png["NiFi Cluster with TLS Toolkit Certificates Diagram"]
. Generate cluster node certificate signing request (one for each node).
- `openssl req -new -key nifi1.key -out nifi1.csr -subj "/CN=nifi1/OU=nifi/" -addext "subjectAltName = IP:192.168.1.1,DNS:localhost"`
- `openssl req -new -key nifi2.key -out nifi2.csr -subj "/CN=nifi2/OU=nifi/" -addext "subjectAltName = IP:192.168.1.2,DNS:localhost"`
- ...
. Create the NiFi Client Certificates. When using the `standalone` mode of the TLS Toolkit, it is important that *all certificates are generated from the same instance, using the same generated NiFi CA certificate to sign each*. The certificates can be generated by a single command, or individually. By default, the Distinguished Name (DN) will be `CN=<provided_hostname>, OU=NIFI`. For more information on toolkit flag options, see link:toolkit-guide.html#usage-8[NiFi Toolkit Guide: TLS Toolkit Usage^].
.. Create a directory for the cluster configuration and navigate to it.
* `mkdir /opt/nifi_cluster_conf && cd /opt/nifi_cluster_conf`
.. Generate the certificates. Running these commands first generates the NiFi CA public certificate and private key if not present, then generates the server certificates, followed by the client certificate necessary for the *Initial Admin Identity*. An alternative command performing all the steps sequentially is also provided.
* `/opt/nifi-toolkit-1.22.0/bin/tls-toolkit.sh standalone -n 'node1.nifi' -c 'ca.nifi'` -- Generates the NiFi CA (`ca.nifi`) certificate and key if not present and generates and signs `node1` certificate, placing the `keystore.jks`, `truststore.jks`, and populated `nifi.properties` in a subdirectory called `node1.nifi`
+
--
_Note the creation of the CA certificate and key_
[source]
----
% /opt/nifi-toolkit-1.22.0/bin/tls-toolkit.sh standalone -n 'node1.nifi' -c 'ca.nifi'
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandaloneCommandLine - No nifiPropertiesFile specified, using embedded one.
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Running standalone certificate generation with output directory ../nifi_cluster_conf
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Generated new CA certificate ../nifi_cluster_conf/nifi-cert.pem and key ../nifi_cluster_conf/nifi-key.key
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Writing new ssl configuration to ../nifi_cluster_conf/node1.nifi
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Successfully generated TLS configuration for node1.nifi 1 in ../nifi_cluster_conf/node1.nifi
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - No clientCertDn specified, not generating any client certificates.
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - tls-toolkit standalone completed successfully
% ls -alGh node1.nifi
total 56
drwx------@ 5 johndoe wheel 160B Jun 26 17:33 .
drwxr-xr-x@ 5 johndoe wheel 160B Jun 26 17:33 ..
-rw-------@ 1 johndoe wheel 3.0K Jun 26 17:33 keystore.jks
-rw-------@ 1 johndoe wheel 17K Jun 26 17:33 nifi.properties
-rw-------@ 1 johndoe wheel 929B Jun 26 17:33 truststore.jks
----
--
* `/opt/nifi-toolkit-1.22.0/bin/tls-toolkit.sh standalone -n 'node2.nifi'` -- Generates and signs `node2` certificate with the same CA
+
--
_Note the existing CA certificate being used_
[source]
----
% /opt/nifi-toolkit-1.22.0/bin/tls-toolkit.sh standalone -n 'node2.nifi'
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandaloneCommandLine - No nifiPropertiesFile specified, using embedded one.
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Running standalone certificate generation with output directory ../nifi_cluster_conf
[main] INFO org.apache.nifi.toolkit.tls.util.TlsHelper - Verifying the certificate signature for CN=ca.nifi,OU=NIFI
[main] INFO org.apache.nifi.toolkit.tls.util.TlsHelper - Attempting to verify certificate CN=ca.nifi,OU=NIFI signature with CN=ca.nifi,OU=NIFI
[main] INFO org.apache.nifi.toolkit.tls.util.TlsHelper - Certificate was signed by CN=ca.nifi,OU=NIFI
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Using existing CA certificate ../nifi_cluster_conf/nifi-cert.pem and key ../nifi_cluster_conf/nifi-key.key
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Writing new ssl configuration to ../nifi_cluster_conf/node2.nifi
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Successfully generated TLS configuration for node2.nifi 1 in ../nifi_cluster_conf/node2.nifi
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - No clientCertDn specified, not generating any client certificates.
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - tls-toolkit standalone completed successfully
----
--
* `/opt/nifi-toolkit-1.22.0/bin/tls-toolkit.sh standalone -n 'node3.nifi'` -- Generates and signs `node3` certificate with the same CA
+
[source]
----
% /opt/nifi-toolkit-1.22.0/bin/tls-toolkit.sh standalone -n 'node3.nifi'
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandaloneCommandLine - No nifiPropertiesFile specified, using embedded one.
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Running standalone certificate generation with output directory ../nifi_cluster_conf
[main] INFO org.apache.nifi.toolkit.tls.util.TlsHelper - Verifying the certificate signature for CN=ca.nifi,OU=NIFI
[main] INFO org.apache.nifi.toolkit.tls.util.TlsHelper - Attempting to verify certificate CN=ca.nifi,OU=NIFI signature with CN=ca.nifi,OU=NIFI
[main] INFO org.apache.nifi.toolkit.tls.util.TlsHelper - Certificate was signed by CN=ca.nifi,OU=NIFI
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Using existing CA certificate ../nifi_cluster_conf/nifi-cert.pem and key ../nifi_cluster_conf/nifi-key.key
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Writing new ssl configuration to ../nifi_cluster_conf/node3.nifi
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Successfully generated TLS configuration for node3.nifi 1 in ../nifi_cluster_conf/node3.nifi
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - No clientCertDn specified, not generating any client certificates.
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - tls-toolkit standalone completed successfully
----
* `/opt/nifi-toolkit-1.22.0/bin/tls-toolkit.sh standalone -C 'CN=my_username'` -- Generates and signs `my_username` client certificate with the same CA
+
[source]
----
% /opt/nifi-toolkit-1.22.0/bin/tls-toolkit.sh standalone -C 'CN=my_username'
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandaloneCommandLine - No nifiPropertiesFile specified, using embedded one.
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Running standalone certificate generation with output directory ../nifi_cluster_conf
[main] INFO org.apache.nifi.toolkit.tls.util.TlsHelper - Verifying the certificate signature for CN=ca.nifi,OU=NIFI
[main] INFO org.apache.nifi.toolkit.tls.util.TlsHelper - Attempting to verify certificate CN=ca.nifi,OU=NIFI signature with CN=ca.nifi,OU=NIFI
[main] INFO org.apache.nifi.toolkit.tls.util.TlsHelper - Certificate was signed by CN=ca.nifi,OU=NIFI
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Using existing CA certificate ../nifi_cluster_conf/nifi-cert.pem and key ../nifi_cluster_conf/nifi-key.key
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - No hostnames specified, not generating any host certificates or configuration.
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Generating new client certificate ../nifi_cluster_conf/CN=my_username.p12
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - Successfully generated client certificate ../nifi_cluster_conf/CN=my_username.p12
[main] INFO org.apache.nifi.toolkit.tls.standalone.TlsToolkitStandalone - tls-toolkit standalone completed successfully
----
+
--
The resulting directory will contain 7 new entries:
. Generate cluster node certificate, using certificate authority key (one for each node).
- `openssl x509 -req -in nifi1.csr -CA ca.cer -CAkey ca.key -CAcreateserial -out nifi1.cer -days 365 -sha256 -copy_extensions=copyall`
- `openssl x509 -req -in nifi2.csr -CA ca.cer -CAkey ca.key -CAcreateserial -out nifi1.cer -days 365 -sha256 -copy_extensions=copyall`
- ...
** `CN=my_username.p12` -- The client certificate in a PKCS12 keystore
** `CN=my_username.password` -- The corresponding file containing the randomly-generated password. Use `-b` or `--clientCertPassword` when generating to specify a password
** `nifi-cert.pem` -- The CA certificate in PEM format
** `nifi-key.key` -- The corresponding CA private key in PEM format
** `node1.nifi/` -- The directory containing `node1` keystore and related files
** `node2.nifi/` -- The directory containing `node2` keystore and related files
** `node3.nifi/` -- The directory containing `node3` keystore and related files
--
Optional command to execute all steps together using the toolkit pattern syntax:
* `/opt/nifi-toolkit-1.22.0/bin/tls-toolkit.sh standalone -n 'node[1-3].nifi' -C 'CN=my_username' -c 'ca.nifi'` -- Performs all steps listed above simultaneously
. Create a new `nifi_cluster` folder in an appropriate location. In this example, where all three nodes will run on the same machine, the `/etc/nifi_cluster` directory is used. All further instructions occur from this directory.
* `mkdir /etc/nifi_cluster` -- Creates the working directory
* `cd /etc/nifi_cluster` -- Change to the created directory
. Copy the NiFi installation folder (i.e. `nifi-1.22.0`) to a new folder for *each* node in the `nifi_cluster` folder created in the previous step.
* `cp -R /etc/nifi-1.22.0 node1.nifi` -- Creates the `node1` directory and copies the NiFi application into it
* `cp -R /etc/nifi-1.22.0 node2.nifi` -- Creates the `node2` directory and copies the NiFi application into it
* `cp -R /etc/nifi-1.22.0 node3.nifi` -- Creates the `node3` directory and copies the NiFi application into it
. Copy the generated `keystore.jks`, `truststore.jks`, and `nifi.properties` to the `conf/` directory of *each* node.
* `cp -R /etc/nifi_cluster_configuration/node1.nifi/* node1.nifi/conf` -- Copies the `node1` files
* `cp -R /etc/nifi_cluster_configuration/node2.nifi/* node2.nifi/conf` -- Copies the `node2` files
* `cp -R /etc/nifi_cluster_configuration/node3.nifi/* node3.nifi/conf` -- Copies the `node3` files
. Modify the `nifi.properties` file for each node to set the appropriate ports and enable the embedded link:https://zookeeper.apache.org/[ZooKeeper^] server. *If the nodes are being deployed to separate physical or virtual machines (such that each is treated as an independent host for networking), modifying the ports is not required, but enabling the embedded ZooKeeper servers is*. If the nodes are being deployed on the same machine such that the ports cannot conflict, all parts of this step are required. This port selection convention follows the pattern defined at the top of this section, where the last digit corresponds to the node identifier. For more information on ZooKeeper configuration for NiFi, see link:administration-guide.html#embedded_zookeeper[NiFi Administrator's Guide: Embedded ZooKeeper^].
+
NOTE: The `nifi.cluster.load.balance.host=` entry must be manually populated here because it was added after the TLS Toolkit was last updated. The toolkit correctly populates the hostname in all other necessary properties.
NOTE: Starting with version 1.14.0, NiFi requires a value for `nifi.sensitive.props.key`. Set the same value on each node.
. Generate cluster node certificate chain (one for each node).
- `cat ca.cer nifi1.cer >nifi1.chain.cer`
- `cat ca.cer nifi2.cer >nifi2.chain.cer`
- ...
* `$EDITOR node1.nifi/conf/nifi.properties` -- Opens the `nifi.properties` file in a text editor
* Update the following lines:
** `nifi.state.management.embedded.zookeeper.start=false` -> `nifi.state.management.embedded.zookeeper.start=true`
** `nifi.remote.input.socket.port=10443` -> `nifi.remote.input.socket.port=10441`
** `nifi.web.https.port=9443` -> `nifi.web.https.port=9441`
** `nifi.sensitive.props.key=` -> `nifi.sensitive.props.key=<secretKey>`
** `nifi.cluster.is.node=false` -> `nifi.cluster.is.node=true`
** `nifi.cluster.node.protocol.port=11443` -> `nifi.cluster.node.protocol.port=11441`
** `nifi.cluster.load.balance.host=` -> `nifi.cluster.load.balance.host=node1.nifi`
** `nifi.cluster.load.balance.port=6342` -> `nifi.cluster.load.balance.port=6341`
** `nifi.zookeeper.connect.string=` -> `nifi.zookeeper.connect.string=node1.nifi:2181,node2.nifi:2182,node3.nifi:2183`
* `$EDITOR node2.nifi/conf/nifi.properties` -- Opens the `nifi.properties` file in a text editor. _Note that the `nifi.cluster.load.balance.port=6342` does not need to change for `node2` and is included for completeness_
* Update the following lines:
** `nifi.state.management.embedded.zookeeper.start=false` -> `nifi.state.management.embedded.zookeeper.start=true`
** `nifi.remote.input.socket.port=10443` -> `nifi.remote.input.socket.port=10442`
** `nifi.web.https.port=9443` -> `nifi.web.https.port=9442`
** `nifi.sensitive.props.key=` -> `nifi.sensitive.props.key=<secretKey>`
** `nifi.cluster.is.node=false` -> `nifi.cluster.is.node=true`
** `nifi.cluster.node.protocol.port=11443` -> `nifi.cluster.node.protocol.port=11442`
** `nifi.cluster.load.balance.host=` -> `nifi.cluster.load.balance.host=node2.nifi`
** `nifi.cluster.load.balance.port=6342` -> `nifi.cluster.load.balance.port=6342`
** `nifi.zookeeper.connect.string=` -> `nifi.zookeeper.connect.string=node1.nifi:2181,node2.nifi:2182,node3.nifi:2183`
* `$EDITOR node3.nifi/conf/nifi.properties` -- Opens the `nifi.properties` file in a text editor. _Note that some of the ports do not need to change for `node3` and are included for completeness_
* Update the following lines:
** `nifi.state.management.embedded.zookeeper.start=false` -> `nifi.state.management.embedded.zookeeper.start=true`
** `nifi.remote.input.socket.port=10443` -> `nifi.remote.input.socket.port=10443`
** `nifi.web.https.port=9443` -> `nifi.web.https.port=9443`
** `nifi.sensitive.props.key=` -> `nifi.sensitive.props.key=<secretKey>`
** `nifi.cluster.is.node=false` -> `nifi.cluster.is.node=true`
** `nifi.cluster.node.protocol.port=11443` -> `nifi.cluster.node.protocol.port=11443`
** `nifi.cluster.load.balance.host=` -> `nifi.cluster.load.balance.host=node3.nifi`
** `nifi.cluster.load.balance.port=6342` -> `nifi.cluster.load.balance.port=6343`
** `nifi.zookeeper.connect.string=` -> `nifi.zookeeper.connect.string=node1.nifi:2181,node2.nifi:2182,node3.nifi:2183`
. Update the `zookeeper.properties` file on each node. This file contains the addresses of each embedded ZooKeeper server in the cluster. The `zookeeper.properties` file can be identical on each embedded ZooKeeper server (assuming no other changes were made), so the modified file will be copied to the other nodes.
* `$EDITOR node1.nifi/conf/zookeeper.properties` -- Opens the `zookeeper.properties` file in a text editor
* Update the following lines:
** `server.1=` -> `server.1=node1.nifi:2881:3881;2181`
** Add the line `server.2=node2.nifi:2882:3882;2182`
** Add the line `server.3=node3.nifi:2883:3883;2183`
* `cp node1.nifi/conf/zookeeper.properties node2.nifi/conf/zookeeper.properties` -- Copies the modified `zookeeper.properties` file from `node1` to `node2`
* `cp node1.nifi/conf/zookeeper.properties node3.nifi/conf/zookeeper.properties` -- Copies the modified `zookeeper.properties` file from `node1` to `node3`
. Create the `myid` file on each node to identify the embedded ZooKeeper server.
* `mkdir -p node1.nifi/state/zookeeper` -- Creates the ZooKeeper directory on `node1`
* `echo 1 >> node1.nifi/state/zookeeper/myid` -- Creates the `myid` file with the `node1` identifier
* `mkdir -p node2.nifi/state/zookeeper` -- Creates the ZooKeeper directory on `node2`
* `echo 2 >> node2.nifi/state/zookeeper/myid` -- Creates the `myid` file with the `node2` identifier
* `mkdir -p node3.nifi/state/zookeeper` -- Creates the ZooKeeper directory on `node3`
* `echo 3 >> node3.nifi/state/zookeeper/myid` -- Creates the `myid` file with the `node3` identifier
. Update the `state-management.xml` file on each node to allow ZooKeeper connections. The `state-management.xml` file can be identical on each node (assuming no other changes were made), so the modified file will be copied to the other nodes.
* `$EDITOR node1.nifi/conf/state-management.xml` -- Opens the `state-management.xml` file in a text editor
* Update the following line:
** `<property name="Connect String"></property>` -> `<property name="Connect String">node1.nifi:2181,node2.nifi:2182,node3.nifi:2183</property>`
* `cp node1.nifi/conf/state-management.xml node2.nifi/conf/state-management.xml` -- Copies the modified `state-management.xml` file from `node1` to `node2`
* `cp node1.nifi/conf/state-management.xml node3.nifi/conf/state-management.xml` -- Copies the modified `state-management.xml` file from `node1` to `node3`
. Update the `authorizers.xml` file. This file contains the *Initial Node Identities* and *Initial User Identities*. The *users* consist of all human users _and_ all nodes in the cluster. The `authorizers.xml` file can be identical on each node (assuming no other changes were made), so the modified file will be copied to the other nodes.
+
NOTE: Each `Initial User Identity` must have a **unique** name (`Initial User Identity 1`, `Initial User Identity 2`, etc.).
. Generate certificate authority keystore.
- `keytool -importcert -keystore trust.p12 -storetype PKCS12 -file ca.cer -alias 1`
* `$EDITOR node1.nifi/conf/authorizers.xml` -- Opens the `authorizers.xml` file in a text editor
* Update the following lines:
** In the `<userGroupProvider>` section, `<property name="Initial User Identity 1"></property>` -> `<property name="Initial User Identity 1">CN=my_username</property>` -- Adds an initial user with the DN generated in the client certificate
** In the `<userGroupProvider>` section, add the line `<property name="Initial User Identity 2">CN=node1.nifi, OU=NIFI</property>` -- Adds an initial user for `node1`
** In the `<userGroupProvider>` section, add the line `<property name="Initial User Identity 3">CN=node2.nifi, OU=NIFI</property>` -- Adds an initial user for `node2`
** In the `<userGroupProvider>` section, add the line `<property name="Initial User Identity 4">CN=node3.nifi, OU=NIFI</property>` -- Adds an initial user for `node3`
+
[source,xml]
<userGroupProvider>
<identifier>file-user-group-provider</identifier>
<class>org.apache.nifi.authorization.FileUserGroupProvider</class>
<property name="Users File">./conf/users.xml</property>
<property name="Legacy Authorized Users File"></property>
<property name="Initial User Identity 1">CN=my_username</property>
<property name="Initial User Identity 2">CN=node1.nifi, OU=NIFI</property>
<property name="Initial User Identity 3">CN=node2.nifi, OU=NIFI</property>
<property name="Initial User Identity 4">CN=node3.nifi, OU=NIFI</property>
</userGroupProvider>
. Generate cluster node keystore (one for each node).
- `openssl pkcs12 -export -out nifi1.p12 -inkey nifi1.key -in nifi1.chain.cer`
- `openssl pkcs12 -export -out nifi2.p12 -inkey nifi2.key -in nifi2.chain.cer`
- ...
** In the `<accessPolicyProvider>` section, `<property name="Initial Admin Identity"></property>` -> `<property name="Initial Admin Identity">CN=my_username</property>` -- Adds an initial admin with the DN generated in the client certificate
** In the `<accessPolicyProvider>` section, `<property name="Node Identity 1"></property>` -> `<property name="Node Identity 1">CN=node1.nifi, OU=NIFI</property>` -- Adds an initial node with the DN generated in the `node1` certificate
** In the `<accessPolicyProvider>` section, add the line `<property name="Node Identity 2">CN=node2.nifi, OU=NIFI</property>`
** In the `<accessPolicyProvider>` section, add the line `<property name="Node Identity 3">CN=node3.nifi, OU=NIFI</property>`
+
[source,xml]
<accessPolicyProvider>
<identifier>file-access-policy-provider</identifier>
<class>org.apache.nifi.authorization.FileAccessPolicyProvider</class>
<property name="User Group Provider">file-user-group-provider</property>
<property name="Authorizations File">./conf/authorizations.xml</property>
<property name="Initial Admin Identity">CN=my_username</property>
<property name="Legacy Authorized Users File"></property>
<property name="Node Identity 1">CN=node1.nifi, OU=NIFI</property>
<property name="Node Identity 2">CN=node2.nifi, OU=NIFI</property>
<property name="Node Identity 3">CN=node3.nifi, OU=NIFI</property>
<property name="Node Group"></property>
</accessPolicyProvider>
After completing these steps, use the generated keystores and truststore as follows:
[options="header"]
|======================
|Node |Keystore |Truststore
|nifi1 |nifi1.p12 |trust.p12
|nifi2 |nifi2.p12 |trust.p12
|... |... |trust.p12
|======================
* `cp node1.nifi/conf/authorizers.xml node2.nifi/conf/authorizers.xml` -- Copies the modified `authorizers.xml` file from `node1` to `node2`
* `cp node1.nifi/conf/authorizers.xml node3.nifi/conf/authorizers.xml` -- Copies the modified `authorizers.xml` file from `node1` to `node3`
. By default, NiFi waits for nodes to join for 5 minutes before the cluster is available. Because the number of nodes is known, this delay can be modified on each node to start up much faster. (Optional)
* `$EDITOR node1.nifi/conf/nifi.properties` -- Opens the `nifi.properties` file in a text editor
* Update the following lines:
** `nifi.cluster.flow.election.max.wait.time=5 mins` -> `nifi.cluster.flow.election.max.wait.time=1 min` -- Changes the flow election wait time to 1 min, speeding up cluster availability
** `nifi.cluster.flow.election.max.candidates=` -> `nifi.cluster.flow.election.max.candidates=3` -- Changes the flow election to occur when 3 nodes are present, speeding up cluster availability
* `$EDITOR node2.nifi/conf/nifi.properties` -- Opens the `nifi.properties` file in a text editor
* Update the following lines:
** `nifi.cluster.flow.election.max.wait.time=5 mins` -> `nifi.cluster.flow.election.max.wait.time=1 min` -- Changes the flow election wait time to 1 min, speeding up cluster availability
** `nifi.cluster.flow.election.max.candidates=` -> `nifi.cluster.flow.election.max.candidates=3` -- Changes the flow election to occur when 3 nodes are present, speeding up cluster availability
* `$EDITOR node3.nifi/conf/nifi.properties` -- Opens the `nifi.properties` file in a text editor
* Update the following lines:
** `nifi.cluster.flow.election.max.wait.time=5 mins` -> `nifi.cluster.flow.election.max.wait.time=1 min` -- Changes the flow election wait time to 1 min, speeding up cluster availability
** `nifi.cluster.flow.election.max.candidates=` -> `nifi.cluster.flow.election.max.candidates=3` -- Changes the flow election to occur when 3 nodes are present, speeding up cluster availability
. Start the NiFi cluster. Once all three nodes have started and joined the cluster, the flow is agreed upon and a cluster coordinator is elected, the UI is available on any of the three nodes.
* `./node1.nifi/bin/nifi.sh start` -- Starts `node1`
* `./node2.nifi/bin/nifi.sh start` -- Starts `node2`
* `./node3.nifi/bin/nifi.sh start` -- Starts `node3`
. Wait approximately 30 seconds and open the web browser to link:https://node3.nifi:9443/nifi[`https://node3.nifi:9443/nifi`^]. The cluster should be available. _Note that the Initial Admin Identity has no permissions on the root process group. This is an artifact of legacy design decisions where the root process group ID is not known at initial start time._
+
--
_The running cluster_
image::nifi-secure-cluster-no-permissions.png["NiFi secure cluster running with no Initial Admin Identity permissions"]
_The cluster status from the global menu at the top right_
image::nifi-secure-cluster-status.png["NiFi secure cluster status pane"]
--
. To update the Initial Admin Identity's permissions for the root process group, stop each node in the cluster and remove the `authorizations.xml` and `users.xml` file from each node. These files will be regenerated when the node starts again and be populated with the correct permissions.
* `./node1.nifi/bin/nifi.sh stop` -- Stops `node1`
* `rm node1.nifi/conf/authorizations.xml node1.nifi/conf/users.xml` -- Removes the `authorizations.xml` and `users.xml` for `node1`
* `./node2.nifi/bin/nifi.sh stop` -- Stops `node2`
* `rm node2.nifi/conf/authorizations.xml node2.nifi/conf/users.xml` -- Removes the `authorizations.xml` and `users.xml` for `node2`
* `./node3.nifi/bin/nifi.sh stop` -- Stops `node3`
* `rm node3.nifi/conf/authorizations.xml node3.nifi/conf/users.xml` -- Removes the `authorizations.xml` and `users.xml` for `node3`
. Start the nodes again.
* `./node1.nifi/bin/nifi.sh start` -- Starts `node1`
* `./node2.nifi/bin/nifi.sh start` -- Starts `node2`
* `./node3.nifi/bin/nifi.sh start` -- Starts `node3`
+
--
_The running cluster with permissions_
image::nifi-secure-cluster-permissions.png["NiFi secure cluster running with Initial Admin Identity permissions"]
--