General

In order to view data in your Kafka cluster you must first create a connection to it. This can be done using the 'Add Cluster' toolbar button or the 'Add New Connection' menu item in the File-menu. In the 'Add Cluster' dialog you can provide the following values under the General-section

• Cluster Name - name you want to give the cluster you're connecting to
• Bootstrap Servers - Bootstrap servers/ports configured in your cluster
• Version - version of the cluster
• Zookeeper Host - hostname or IP address of the zookeeper host in the cluster
• Zookeeper Port - port of the zookeeper host
• chroot path - path where the kafka cluster data appears in Zookeeper. The default value is correct in most cases.

Depending on your cluster configuration you must enter values for either Bootstrap servers, Zookeeper host/port or both. In the following cases you must enter values in the 'Bootstrap servers' field in order to be able to connect to your Kafka cluster and leave the Zookeeper host/port fields blank:

• Your Kafka cluster uses KRaft and does not have Zookeeper hosts at all.
• You have no access to the Zookeeper host in your cluster due to security, firewall or other reasons
• The correct broker hosts/ports cannot be determined from the data in the Zookeeper. This can happen if you have configured support for multiple protocols in your cluster.

Notice that if you do not provide the Zookeeper host/port values, some features in Offset Explorer may not be available (For example the Zookeeper Browser).

Plaintext

If your cluster is configured for plaintext security (typically in test environments only) you do not need to configure any additional security attributes. You can just click on Test to test that your connection is working properly or Add to add the server connection without testing it first.

SASL

If your cluster is configured for SASL (plaintext or SSL) you must either specify the JAAS config in the UI or pass in your JAAS config file to Offset Explorer when you start it. The exact contents of the JAAS file depend on the configuration of your cluster, please refer to the Kafka documentation.

On Windows you need to start Offset Explorer as follows

• offsetexplorer.exe -J-Djava.security.auth.login.config=c:/client_jaas.conf

On Linux you need to start Offset Explorer as follows

• offsetexplorer -J-Djava.security.auth.login.config=/client_jaas.conf

On MacOS you need to start Offset Explorer using offsetexplorer.sh located in the following folder

• /Applications/Offset Explorer.app/Contents/java/app

Before that, you must configure the provided client_jaas.conf file to match your Kafka cluster configuration

If you do not pass the JAAS config file at the startup of Offset Explorer, you must specify it under the JAAS Config tab for each connection.

If you are using SASL Plaintext you typically must change the sasl.mechanism client property to PLAIN. This property can be entered in the 'SASL Mechanism' text field under the 'Advanced' section.

SSL

If your Kafka cluster is configured to use SSL you may need to set various SSL configuration parameters. Unless your Kafka brokers are using a server certificate issued by a public CA, you need to point to a local truststore that contains the self signed root certificate that signed your brokers certificate. You also need to enter the password for this truststore.

If the SAN(s) in your server certificate do not match the actual hostname of the brokers you are connecting to, you will receive an SSL error (No subject alternative DNS name matching xxx found) when you try to connect. You can avoid this by unchecking the 'Validate SSL endpoint hostname' checkbox in the 'Broker security' section. This will set the ssl.endpoint.identification.algorithm client property to null.

If your Kafka cluster requires a client certificate (two-way authentication) you also need to configure your keystore attributes. The keystore contains the private key that you use to authenticate to your Kafka brokers. You also need to configure a password for the keystore as well as password for the private key in the keystore.

Azure Event Hubs

In order to connect Offset Explorer to an Azure Event Hub, you must first make sure that "Kafka Surfaces" is enabled. This can be confirmed by navigating to the Event Hubs namespace page and seeing if it is enabled.

Once this has been confirmed, navigate to the "Shared access policies" menu item in the Event Hubs namespace. You can either use the RootManageSharedAccessKey, or make your own policy. Once you have chosen the policy, click on it and copy the connection string–primary key value.

Once the link has been copied, you can open Offset Explorer and add a new connection. In the properties tab, choose a name and version for the cluster. Note that Azure Event Hubs do not support access to Zookeeper so you must leave the Zookeeper host field empty. Enter the bootstrap server(s) that match your configuration. Make sure to use port number 9093, as it differs from the standard port for Kafka (9092).

In the security tab, change the security type from plaintext to SASL SSL.

In the Advanced tab, enter PLAIN into the SASL mechanism field.

For the JAAS Config tab, you will need to enter the following information (note that the password is equal to the connection string–primary key link that you copied earlier):

Once all this information has been entered, you can click "Add" to add the connection.

Amazon MSK - SCRAM

A quick method to connect to your Amazon MSK cluster is to configure your MSK security settings to allow SASL/SCRAM authentication. In order to connect Offset Explorer to your Amazon MSK environment using SASL/SCRAM authentication, you will need to add the following settings when creating your cluster in Offset Explorer:

Properties tab: Enter the bootstrap servers that match your MSK configuration. Confirm that zookeeper host is left blank. Pick the version number that matches your Amazon MSK cluster.

Security tab: Confirm that the broker security type is SASL SSL.

Advanced tab: Enter the following into the SASL Mechanism box: SCRAM-SHA-512

JAAS Config tab: Copy the following, switching out "myuser" for correct username and "mypassword" for correct password. These credentials are stored in the AWS Secrets Manager secret that is associated with your MSK SASL/SCRAM authentication.

Once these settings for the cluster have been given, you can add the server connection by clicking "Add" and connect.

Amazon MSK - IAM

In order to connect Offset Explorer to your Amazon MSK environment using IAM authentication, you will need to add the following settings when creating your cluster in Offset Explorer.

Properties tab: Enter the bootstrap servers that match your MSK configuration. You can find these values in the AWS console. Pick the version number that matches your Amazon MSK cluster. Confirm that zookeeper host is left blank.

Security tab: Confirm that the broker security type is SASL SSL.

Enter the following values in the Advanced tab:
SASL Mechanism: AWS_MSK_IAM
SASL Callback Handler Class: software.amazon.msk.auth.iam.IAMClientCallbackHandler

JAAS Config tab: Use the following value in the JAAS config field.

Once these settings for the cluster have been given, you can add the server connection by clicking "Add" and connect.

Confluent Cloud

In order to connect Offset Explorer to a Confluent Cloud environment, you will need to add the following settings when creating your cluster in Offset Explorer:

Properties tab: Confirm the bootstrap servers input is correctly given and confirm that zookeeper host is left blank.

Security tab: Confirm that the broker security type is SASL SSL.

Advanced tab: Enter the following into the SASL Mechanism box: PLAIN

JAAS Config tab: Copy the following, switching out "myapikey" and "myapisecret" for correct values.

Once these settings for the cluster have been given, you can add the cluster by clicking "Add" and connect.