Introduction

When Spring Kafka fails to authenticate with a SASL-protected broker, the root cause is often not Kafka itself but how the client properties were mapped into application.properties. With Spring Boot, the important detail is that Kafka client settings must usually go under spring.kafka.properties.*, while only a few top-level settings such as bootstrap-servers have dedicated Boot keys. Once that separation is clear, JAAS and SASL configuration becomes much easier to reason about.

Put Kafka Client Properties Under spring.kafka.properties.*

Spring Boot exposes many Kafka settings directly, but low-level Kafka client properties such as security.protocol, sasl.mechanism, and sasl.jaas.config normally belong under the spring.kafka.properties prefix.

A common SASL/PLAIN example looks like this:

1spring.kafka.bootstrap-servers=broker1:9092,broker2:9092
2spring.kafka.properties.security.protocol=SASL_SSL
3spring.kafka.properties.sasl.mechanism=PLAIN
4spring.kafka.properties.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="my-user" password="my-password";

That format matters. If you place security.protocol or sasl.mechanism at the wrong property level, Spring Boot may never pass them to the Kafka client.

Understand What sasl.jaas.config Replaces

There are two common ways to provide JAAS settings:

• an external JAAS file through JVM system properties
• an inline sasl.jaas.config client property

For Spring Boot applications, the inline property is usually the simplest option because it keeps the configuration with the rest of the Kafka client settings.

Example for SCRAM:

spring.kafka.properties.security.protocol=SASL_SSL
spring.kafka.properties.sasl.mechanism=SCRAM-SHA-512
spring.kafka.properties.sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required username="service-user" password="secret";

If you use sasl.jaas.config, you usually do not need a separate JAAS file for that client login path.

Match the Mechanism and Protocol Exactly

Authentication fails quickly if the broker and client disagree on either the SASL mechanism or the transport protocol.

Typical combinations are:

• 'SASL_PLAINTEXT with PLAIN'
• 'SASL_SSL with PLAIN'
• 'SASL_SSL with SCRAM-SHA-256'
• 'SASL_SSL with SCRAM-SHA-512'
• 'SASL_PLAINTEXT or SASL_SSL with GSSAPI for Kerberos environments'

If the cluster expects SASL_SSL and the application uses SASL_PLAINTEXT, the connection fails before your consumer or producer logic even starts.

A Small End-to-End Spring Example

This consumer configuration uses Boot's properties and lets Spring create the Kafka client with the SASL settings already applied:

1import org.springframework.kafka.annotation.KafkaListener;
2import org.springframework.stereotype.Component;
3
4@Component
5public class OrdersListener {
6
7    @KafkaListener(topics = "orders", groupId = "orders-service")
8    public void handle(String payload) {
9        System.out.println("Received: " + payload);
10    }
11}

With the earlier application.properties, Spring Boot passes the authentication settings into the underlying Kafka consumer factory automatically.

In other words, if the properties are correct, you usually do not need to manually build JAAS objects in Java code.

SSL Adds Another Layer

If the cluster uses SASL_SSL, then SASL is only part of the story. You may also need truststore settings:

1spring.kafka.properties.security.protocol=SASL_SSL
2spring.kafka.properties.sasl.mechanism=PLAIN
3spring.kafka.properties.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="my-user" password="my-password";
4spring.kafka.properties.ssl.truststore.location=/opt/certs/kafka.truststore.jks
5spring.kafka.properties.ssl.truststore.password=changeit

A lot of "JAAS is not working" reports are actually TLS trust failures or protocol mismatches that happen before authentication succeeds.

A Good Troubleshooting Order

When the config does not work, check in this order:

1. confirm the broker address is reachable
2. confirm the broker expects the same security.protocol
3. confirm the SASL mechanism matches the server
4. confirm sasl.jaas.config uses the correct login module and credentials
5. if using SSL, confirm the truststore is valid

This sequence prevents a lot of misdiagnosis.

It also helps to enable Kafka client logging while testing. Authentication and handshake failures are usually clearer in the client logs than in the high-level Spring exception message.

Common Pitfalls

One common mistake is placing Kafka client properties at the wrong level in application.properties. Settings such as security.protocol and sasl.mechanism usually need the spring.kafka.properties.* prefix.

Another mistake is mixing the inline sasl.jaas.config approach with an external JAAS file without realizing which one the application is actually using.

Developers also often focus on JAAS syntax when the real problem is a protocol mismatch such as SASL_PLAINTEXT versus SASL_SSL, or a missing truststore.

Finally, make sure the login module matches the mechanism. PlainLoginModule is not interchangeable with SCRAM or Kerberos login modules.

Summary

• In Spring Boot, low-level Kafka client settings usually belong under spring.kafka.properties.*.
• 'sasl.jaas.config is often the simplest way to provide JAAS credentials in a Spring Kafka app.'
• 'security.protocol, sasl.mechanism, and the login module must match the broker configuration exactly.'
• If the cluster uses SASL_SSL, verify TLS truststore settings as well as SASL settings.
• Troubleshoot in layers: connectivity, protocol, SASL mechanism, JAAS credentials, then SSL details.