skip to content

How do you configure a Kafka client to authenticate with mTLS, and what keystore/truststore settings are required?

level: middleimportance: must knowfreq 60%

answer

  1. security.protocol=SSL
  2. keystore = client cert+key
  3. truststore = broker's CA
  4. ssl.key.password vs keystore.password
  5. broker truststore must have client CA

basics

~10 s

Set security.protocol=SSL, point ssl.keystore.location/password (and ssl.key.password) at the client's keystore holding its cert+private key, and ssl.truststore.location/password at the truststore holding the broker's CA. The broker side must have ssl.client.auth=required.

solid answer

~40 s

On the client you set `security.protocol=SSL` (or `SASL_SSL` if SASL is also in play). The **truststore** (`ssl.truststore.location`, `ssl.truststore.password`) holds the CA that signed the broker cert, so the client can validate the broker. The **keystore** (`ssl.keystore.location`, `ssl.keystore.password`, and `ssl.key.password` for the key entry) holds the client's own certificate and private key — this is what makes it mTLS rather than one-way TLS. Stores are typically JKS or PKCS12 (`ssl.keystore.type`). On the broker listener you must set `ssl.client.auth=required` so the broker actually requests and enforces a client cert, and the broker's truststore must contain the CA that signed the client certs. If the client omits a keystore while the broker requires client auth, the handshake fails. The client cert's DN becomes the authenticated principal used for ACLs.

code

properties · 8 lines
properties
security.protocol=SSL
ssl.truststore.location=/etc/kafka/secrets/client.truststore.jks
ssl.truststore.password=changeit
ssl.keystore.location=/etc/kafka/secrets/client.keystore.jks
ssl.keystore.password=changeit
ssl.key.password=changeit
ssl.keystore.type=PKCS12
ssl.endpoint.identification.algorithm=https

go deeper

for a junior

Recall that the client needs a keystore (its cert) plus a truststore (broker CA) and security.protocol=SSL.

for a middle

Configure all the ssl.* keys correctly, including the keystore-vs-key password distinction and store types.

for a senior

Diagnose handshake failures by reasoning about which side's truststore is missing which CA, and the hostname-verification trap.

for a principal

Standardize keystore distribution/rotation, mandate hostname verification, and decide JKS vs PKCS12/PEM across the fleet.

## The two stores, again, but precisely Every TLS peer can have up to two stores: - **Truststore** — the set of CA certificates you trust. Used to **validate the certificate the other party sends**. - **Keystore** — your **own** private key plus the matching certificate (and usually the CA chain). Used to **present your identity**. For mTLS both client and broker need both stores: each presents an identity and each validates the other. ## Minimal client configuration (mTLS only) ```properties security.protocol=SSL # validate the broker ssl.truststore.location=/etc/kafka/secrets/client.truststore.jks ssl.truststore.password=changeit ssl.truststore.type=JKS # present the client's identity (this is what makes it mutual) ssl.keystore.location=/etc/kafka/secrets/client.keystore.jks ssl.keystore.password=changeit ssl.key.password=changeit ssl.keystore.type=JKS ``` Key points: - `security.protocol=SSL` selects the encrypted, cert-based listener. If SASL also authenticates, use `SASL_SSL` — but then SASL provides identity and certs may just encrypt; pure mTLS auth uses `SSL`. - `ssl.key.password` is the password protecting the **private key entry** inside the keystore, which can differ from `ssl.keystore.password` (the password for the store file itself). - `ssl.keystore.type` / `ssl.truststore.type` is usually `JKS` or `PKCS12` (PKCS12 is the modern default). You can also use `PEM` type with `ssl.keystore.key`/`ssl.keystore.certificate.chain` inline. - `ssl.endpoint.identification.algorithm` defaults to `https`, which means the client verifies the broker hostname matches the cert SAN. Setting it to empty disables hostname verification — convenient in dev, dangerous in prod (enables MITM). ## Broker side (so the client cert is actually demanded) ```properties listeners=SSL://:9093 ssl.keystore.location=/etc/kafka/secrets/broker.keystore.jks ssl.keystore.password=changeit ssl.key.password=changeit ssl.truststore.location=/etc/kafka/secrets/broker.truststore.jks ssl.truststore.password=changeit ssl.client.auth=required ``` The **broker truststore must contain the CA that signed the client certs**; otherwise the broker rejects the client cert as untrusted. `ssl.client.auth=required` is what turns 'TLS' into 'mTLS authentication'. ## Common failure modes - **No keystore on client + `required` on broker** → handshake fails, broker log shows a missing/empty certificate chain or `bad_certificate`. - **Client CA not in broker truststore** → `certificate_unknown` / unable to find valid certification path. - **Wrong `ssl.key.password`** → `UnrecoverableKeyException` on the side trying to load its key. - **Hostname mismatch** with default `endpoint.identification.algorithm=https` → handshake fails on SAN mismatch; fix the cert SANs, don't blanket-disable verification. ## How identity flows out On success the broker reads the client cert's Subject DN and turns it into `User:<DN>` (subject to `ssl.principal.mapping.rules`). That principal is what ACLs match.

  • Why might a client have a valid keystore but still fail the handshake against the broker?
    The broker's truststore may not contain the CA that signed the client cert, so the broker rejects it as untrusted ('unable to find valid certification path'). The client cert could also be expired or the wrong EKU.
  • What is the difference between ssl.keystore.password and ssl.key.password?
    ssl.keystore.password unlocks the keystore file; ssl.key.password unlocks the individual private-key entry inside it. They can differ; a wrong key password throws UnrecoverableKeyException.

saying these in an interview costs you the question

  • Saying the client only needs a truststore — without a keystore there is no client identity to present.
  • Disabling ssl.endpoint.identification.algorithm in production to 'fix' handshake errors — that opens MITM.
  • Forgetting that the BROKER truststore must trust the client's CA, not just vice versa.

context

resolving links…