Kafka client configuration reference

This topic collects the minimum configuration required for enable the supported authentication mechanisms. You may need to update the client configuration file and the JAAS, depending on the desired authentication mechanism.

Client configuration file

You need to configure at least the following properties in the client.configuration file to enable the authentication mechanisms supported by Kafka.

OAuth
LDAP
PAM
TLS∕SSL
Kerberos
Delegation token

security.protocol=[***SECURITY PROTOCOL***]
sasl.mechanism=OAUTHBEARER
sasl.login.callback.handler.class=org.apache.kafka.common.security.oauthbearer.secured.OAuthBearerLoginCallbackHandler
sasl.oauthbearer.token.endpoint.url=http://[***OAUTH SERVER***]/[***TOKEN ENDPOINT***]

Replace [***SECURITY PROTOCOL***] with either SASL_SSL or SASL_PLAINTEXT. The security protocol you specify depends on whether TLS/SSL encryption is enabled on the broker.

The following properties are only required if TLS/SSL is enabled on the broker.

ssl.truststore.location= [***PATH TO CLIENT TRUSTSTORE***]
ssl.truststore.password=[***PASSWORD***]

This example contains the minimum required TLS/SSL properties. Depending on your requirements and how TLS/SSL is configured on the broker, other properties might be required. For more information regarding TLS/SSL configuration, see Channel Encryption.

sasl.mechanism=PLAIN

The following properties are used for configuring the security protocol.

You can either use SASL_SSL or SASL_PLAINTEXT. Which security protocol you use will depend on whether or not SSL encryption is enabled on the broker. Add one of the following properties to the client.properties file.

If encryption is enabled, use SASL_SSL:
```
security.protocol=SASL_SSL
```
If encryption is not enabled, use SASL_PLAINTEXT:
```
security.protocol=SASL_PLAINTEXT
```

sasl.mechanism=PLAIN

The following properties are used for configuring the security protocol.

If encryption is enabled, use SASL_SSL:
```
security.protocol=SASL_SSL
```
If encryption is not enabled, use SASL_PLAINTEXT:
```
security.protocol=SASL_PLAINTEXT
```

security.protocol=SSL
ssl.truststore.location=[***PATH TO CLIENT TRUSTSTORE***]
ssl.truststore.password=[***PASSWORD***]
ssl.keystore.location=[***PATH TO CLIENT KEYSTORE***]
ssl.keystore.password=[***PASSWORD***]
ssl.key.password=[***PASSWORD***]

Depending on your requirements and broker configuration, other configuration properties might also be needed. The following are some of the most commonly used optional properties:

ssl.provider
ss.cipher.suites
ssl.enabled.protocols
ssl.truststore.type
ssl.keystore.type

security.protocol=SASL_PLAINTEXT
sasl.kerberos.service.name=kafka

: This authentication method is not configured using the client.configuration file.

JAAS configuration

You need to configure at least the following properties in the JAAS to enable the authentication mechanisms supported by Kafka.

OAuth
LDAP
PAM
TLS∕SSL
Kerberos
Delegation token

You have two options when configuring the JAAS. You can either embed the full JAAS configuration in the client.properties file or use a separate JAAS configuration file.

Embed the required properties in the client.properties file with the sasl.jaas.config property.

sasl.jaas.config=org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required clientId="[***CLIENT ID***]" clientSecret="[***CLIENT SECRET***]" scope="[***SCOPE***]";

Use a separate JAAS configuration file:
1. Add a KafkaClient entry with a login module item to your JAAS configuration file.
  You can also create a new JAAS configuration file if you do not have an existing one available.
```
KafkaClient {
  org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required
  clientId="[***CLIENT ID***]"
  clientSecret="[***CLIENT SECRET***]"
  scope="[***SCOPE***]";
};
```
2. Pass the location of your JAAS configuration file as a JVM parameter through a command line interface.
```
export KAFKA_OPTS="-Djava.security.auth.login.config=[***PATH TO JAAS.CONF***]"
```

You have two options when configuring the JAAS. You can either embed the full JAAS configuration in the client.properties file or use a separate JAAS configuration file.

Embed the required properties in the client.properties file with the sasl.jaas.config property.
```
sasl.jaas.config= \ 
org.apache.kafka.common.security.plain.PlainLoginModule required \
    username="[***LDAP USERNAME***]" \
    password="[***LDAP PASSWORD***]";
```
Replace [LDAP_USERNAME] and [LDAP_PASSWORD] with a valid LDAP username and password.
Use a separate JAAS configuration file:
1. Add a KafkaClient entry with a login module item to your JAAS configuration file.
  You can also create a new JAAS configuration file if you do not have an existing one available.
  Example configuration:
```
KafkaClient {
     org.apache.kafka.common.security.plain.PlainLoginModule required
     username="[***LDAP USERNAME***]"
     password="[***LDAP PASSWORD***]";
    };
```
  Replace [LDAP_USERNAME] and [LDAP_PASSWORD] with a valid LDAP username and password.
2. Pass the location of your JAAS configuration file as a JVM parameter through a command line interface.
```
export KAFKA_OPTS="-Djava.security.auth.login.config=[***PATH TO JAAS.CONF***]"
```
  Replace [***PATH TO JAAS.CONF***] with the location of the JAAS configuration file you created.

You have two options when configuring the JAAS. You can either embed the full JAAS configuration in the client.properties file or use a separate JAAS configuration file.

Embed the required properties in the client.properties file with the sasl.jaas.config property.
```
sasl.jaas.config= \ 
org.apache.kafka.common.security.plain.PlainLoginModule required \
    username="[USERNAME]" \
    password="[PASSWORD]";
```
Replace [USERNAME] and [PASSWORD] with a valid username and password.
Use a separate JAAS configuration file:
1. Add a KafkaClient entry with a login module item to your JAAS configuration file.
  You can also create a new JAAS configuration file if you do not have an existing one available.
  Example configuration:
```
KafkaClient {
     org.apache.kafka.common.security.plain.PlainLoginModule required
     username="[USERNAME]"
     password="[PASSWORD]";
    };
```
  Replace [USERNAME] and [PASSWORD] with a valid username and password.
2. Pass the location of your JAAS configuration file as a JVM parameter through a command line interface.
```
export KAFKA_OPTS="-Djava.security.auth.login.config=[PATH_TO_JAAS.CONF]"
```
  Replace [PATH_TO_JAAS.CONF] with the location of the JAAS configuration file you created.

: This step is not applicable for TLS/SSL authentication.

Create a jaas.conf file with either cached credentials or keytabs.

To use cached Kerberos credentials, where you use kinit first, use this configuration:
```
KafkaClient {
com.sun.security.auth.module.Krb5LoginModule required
useTicketCache=true;
};
```

If you use a keytab, use this configuration:

KafkaClient {
com.sun.security.auth.module.Krb5LoginModule required
useKeyTab=true
keyTab="/etc/security/keytabs/mykafkaclient.keytab"
principal="mykafkaclient/clients.hostname.com@EXAMPLE.COM";
};

You have two options when configuring the JAAS. You can either embed the full JAAS configuration in the client.properties file or use a separate JAAS configuration file.

Embed the required properties in the client.properties file with the sasl.jaas.config property.
Example Configuration:
```
sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule  required \
    username="tokenID" \
    password="lAYYSFmLs4bTjf+lTZ1LCHR/ZZFNA==" \
    tokenauth="true";
security.protocol=SASL_SSL
sasl.mechanism=SCRAM-SHA-256
```
Within the JAAS configuration, there are three options that need to be specified. These are the username, password and tokenauth options. The username and password options specify the token ID and token HMAC. The tokenauth option expresses the intent to use token authentication to the server.
Use a separate JAAS configuration file:
1. Add a KafkaClient entry with a login module item to your JAAS configuration file.
  You can also create a new JAAS configuration file if you do not have an existing one available.
  The module has to specify the username, password and tokenauth options. The configuration is similar to the following example:
```
KafkaClient {
org.apache.kafka.common.security.scram.ScramLoginModule  required
    username="tokenID"
    password="lAYYSFmLs4bTjf+lTZ1LCHR/ZZFNA=="
    tokenauth="true";
}
```
  The username and password options specify the token ID and token HMAC. The tokenauth option expresses the intent to use token authentication to the server.
2. Configure the following properties for your clients.
  These properties are added to producer.properties or consumer.properties file that the client uses.
```
security.protocol=SASL_SSL
sasl.mechanism=SCRAM-SHA-256
```
3. Pass the location of your JAAS configuration file as a JVM parameter through a command line interface.
  This sets the JAAS configuration on the Java process level.
```
export KAFKA_OPTS="-Djava.security.auth.login.config=[PATH_TO_JAAS.CONF]"
```