Adding Security to a Running Cluster

This topic describes how to add security (SSL or SASL) to a running cluster.

Migrating Brokers and Clients

You can secure a running cluster using one or more of the supported protocols. This is done in phases:

  1. Incrementally restart the cluster nodes to open additional secured port(s).
  2. Restart clients using the secured rather than PLAINTEXT port (assuming you are securing the client-broker connection).
  3. Incrementally restart the cluster again to enable broker-to-broker security (if this is required).
  4. A final incremental restart to close the PLAINTEXT port.

The specific steps for configuring security protocols are described in the respective sections for SSL and SASL. Follow these steps to enable security for your desired protocol(s).

The security implementation lets you configure different protocols for both broker-client and broker-broker communication. These must be enabled in separate restarts. A PLAINTEXT port must be left open throughout so brokers and/or clients can continue to communicate.

When performing an incremental restart, take into consideration the recommendations for doing rolling restarts to avoid downtime for end users.

For example, if you want to encrypt both broker-client and broker-broker communication with SSL:

  1. In the first incremental restart, open an SSL port on each node:



    In Kafka 1.1 and later, you can update some broker configurations without restarting the broker by adding or removing listeners dynamically. When adding a new listener, provide the security configuration of the listener using the listener prefix{listenerName}. If the new listener uses SASL, then provide the JAAS configuration property sasl.jaas.config with the listener and mechanism prefix. For more details, refer to JAAS.

  2. Then restart the clients, changing their configuration to point at the newly-opened, secured port:


    For more details, refer to Encryption with SSL.

  3. In the second incremental server restart, instruct Apache Kafka® to use SSL as the broker-broker protocol (which will use the same SSL port):

  4. In the final restart, secure the cluster by closing the PLAINTEXT port:


Alternatively, you might choose to open multiple ports so that different protocols can be used for broker-broker and broker-client communication. If you want to use SSL encryption throughout (i.e. for broker-broker and broker-client communication), but also want to add SASL authentication to the broker-client connection:

  1. Open two additional ports during the first restart:

  2. Again, restart the clients, changing their configuration to point at the newly-opened, SASL and SSL secured port:


    For more details, refer to Authentication with SASL.

  3. The second server restart would switch the cluster to use encrypted broker-broker communication using the SSL port you previously opened on port 9092:

  4. The final restart secures the cluster by closing the PLAINTEXT port:


Migrating ZooKeeper

If you are running a version of Kafka that does not support security or you have security disabled and you want to make the cluster secure, then you must perform the following steps to enable ZooKeeper authentication with minimal disruption to your operations:


Migrating ZooKeeper security when the Kafka cluster is not running (no controller node in ZooKeeper) results in a controller node being created, but populated with a null value. In this scenario, leader election may not work properly in subsequent starts of the Kafka cluster.

  1. In, add the authentication provider to enable ZooKeeper security:

    authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider requireClientAuthScheme=sasl
  2. Export the ZooKeeper JAAS file before restarting ZooKeeper:<path>/zookeeper_server_jaas.conf

    The content of zookeeper_server_jaas.conf should look like the following:

    Server {
       org.apache.zookeeper.server.auth.DigestLoginModule required
  3. Perform ZooKeeper rolling restarts with the JAAS login file shown above; this enables brokers to authenticate.

  4. Create the JAAS file for the brokers to authenticate with ZooKeeper. Add the Client information to the broker JAAS configuration and then export the JAAS file:


    The content of the broker JAAS file (kafka_server_jaas.conf) should look like the following:

    Client {
       org.apache.zookeeper.server.auth.DigestLoginModule required
  5. Perform a rolling restart of brokers, this time setting the configuration parameter zookeeper.set.acl to true, which enables the use of secure ACLs when creating znodes.

  6. Execute the ZkSecurityMigrator tool using the script: bin/zookeeper-security-migration with zookeeper.acl set to secure. This tool traverses the corresponding sub-trees, changing the ACLs of the znodes.

If you wish to validate that security has been enabled between the broker and ZooKeeper:

  1. Export the broker JAAS configuration:

  2. Create a new topic named test using the kafka-topic command:

    bin/kafka-topics --zookeepr <zk_host>:<zk_port> --create --topic test --partitions 2 --replication-factor 2
  3. Log in to the zookeeper-shell and check the ACL of the newly-created znode, which should have the ACL enabled:

    bin/zookeeper-shell <zk_host>:<zk_port>
    [zk: localhost:12181(CONNECTED) 9] getAcl /config/topics/test
    : r
    : cdrwa

If you want to turn off authentication in a secure cluster:

  1. Perform a rolling restart of brokers setting the JAAS login file, which enables brokers to authenticate, but setting zookeeper.set.acl to false. At the end of the rolling restart, brokers stop creating znodes with secure ACLs, but are still able to authenticate and manipulate all znodes.
  2. Run the ZkSecurityMigrator tool using the script bin/zookeeper-security-migration with zookeeper.acl set to unsecure. This tool traverses the corresponding sub-trees, changing the ACLs of the znodes.
  3. Perform a second rolling restart of brokers, this time omitting the system property that sets the JAAS login file.

Here is an example of how to run the migration tool:

bin/zookeeper-security-migration --zookeeper.acl=secure --zookeeper.connect=localhost:2181

Run this command to see the full list of parameters:

bin/zookeeper-security-migration --help

Migrating the ZooKeeper ensemble

You must also enable authentication on the ZooKeeper ensemble. This requires that you perform a rolling restart of the ensemble and set a few properties. Refer to the ZooKeeper documentation for more detail: