skip to content

How do you configure a Kafka client and broker for GSSAPI using a keytab, principal, and sasl.kerberos.service.name?

level: middleimportance: must knowfreq 50%

answer

  1. GSSAPI + SASL_SSL + service.name=kafka
  2. Krb5LoginModule useKeyTab/keyTab/principal/storeKey
  3. Inline sasl.jaas.config vs jaas file
  4. service.name must match kafka/<host>
  5. krb5.conf via -Djava.security.krb5.conf

basics

~10 s

Set security.protocol=SASL_SSL, sasl.mechanism=GSSAPI, and sasl.kerberos.service.name=kafka. Provide a JAAS config (via sasl.jaas.config) pointing useKeyTab to a keytab file and the principal that keytab contains.

solid answer

~30 s

On both broker and client you set sasl.mechanism=GSSAPI and security.protocol=SASL_SSL (or SASL_PLAINTEXT), plus sasl.kerberos.service.name=kafka — this must match the service part of the broker's principal kafka/<host>@REALM. Authentication credentials come from a JAAS Krb5LoginModule. Modern Kafka uses inline sasl.jaas.config: 'com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true storeKey=true keyTab="/etc/security/keytabs/kafka_client.keytab" principal="[email protected]";'. The broker has its own keytab and listener.name.<listener>.gssapi.sasl.jaas.config for its kafka/<host> principal. The keytab holds the principal's long-term key so no interactive kinit is needed. krb5.conf (realm + KDC) is supplied via -Djava.security.krb5.conf. The service name plus broker host and realm let the client request the correct service ticket.

code

properties · 8 lines
properties
security.protocol=SASL_SSL
sasl.mechanism=GSSAPI
sasl.kerberos.service.name=kafka
sasl.jaas.config=com.sun.security.auth.module.Krb5LoginModule required \
  useKeyTab=true \
  storeKey=true \
  keyTab="/etc/security/keytabs/kafka_client.keytab" \
  principal="[email protected]";

go deeper

for a junior

Recognize the keytab + principal + service.name trio and that GSSAPI needs a JAAS login module.

for a middle

Configure both inline and file JAAS, set storeKey/useKeyTab correctly, and align service.name with the broker principal.

for a senior

Reason about kvno mismatches, FQDN/hostname pitfalls, and broker vs client JAAS stanzas.

for a principal

Standardize keytab distribution and JAAS templating across a fleet and troubleshoot realm/host resolution at scale.

## What you are wiring together GSSAPI needs four things to line up: the **mechanism**, the **transport protocol**, the **service name**, and the **login credentials** (keytab + principal) plus a **krb5.conf** describing the realm and KDC. ## Properties - `sasl.mechanism=GSSAPI` — selects Kerberos. - `security.protocol=SASL_SSL` (auth + TLS) or `SASL_PLAINTEXT` (auth only). - `sasl.kerberos.service.name=kafka` — the **service** component of the broker principal `kafka/[email protected]`. The client uses this to construct the service principal it requests a ticket for. If it does not match the broker's actual principal, you get 'Server not found in Kerberos database' or GSSAPI failures. ## JAAS login module Kerberos credentials are supplied through JAAS using `Krb5LoginModule`. Two ways: - **Inline** (preferred, per-client): `sasl.jaas.config=com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true storeKey=true keyTab="..." principal="...";` - **File**: set `-Djava.security.auth.login.config=/path/kafka_jaas.conf` containing a `KafkaClient { ... };` (client) or `KafkaServer { ... };` (broker) stanza. Key JAAS options: - `useKeyTab=true` — authenticate from a keytab file (non-interactive, for services). - `keyTab="/path/to.keytab"` — the file holding the principal's key. - `principal="name@REALM"` — which identity in the keytab to use. - `storeKey=true` — keep the key in the Subject so it can be reused / renewed. - `useTicketCache=true` — alternative: use a ticket from `kinit`'s cache instead of a keytab (common for human/interactive use). - `doNotPrompt=true` — never prompt for a password (correct for services). ## Broker side The broker has `KafkaServer` JAAS (or `listener.name.<name>.gssapi.sasl.jaas.config`) with `useKeyTab=true`, its keytab, and `principal="kafka/[email protected]"`. The broker also sets `sasl.enabled.mechanisms=GSSAPI` and includes GSSAPI in `sasl.mechanism.inter.broker.protocol` if brokers authenticate to each other with Kerberos. ## krb5.conf A `[libdefaults]` default_realm plus `[realms]` and `[domain_realm]` mapping. Passed via `-Djava.security.krb5.conf=/etc/krb5.conf`. Without it the JVM cannot find the KDC. ## Edge cases - The principal in JAAS must actually exist in the keytab; list it with `klist -kt the.keytab`. - The keytab's kvno (key version number) must match what the KDC currently has, or you get decrypt errors. - Hostname in the broker principal must match how clients resolve and address the broker (use FQDN, beware short names).

  • When would you use useTicketCache=true instead of useKeyTab=true?
    For interactive/human logins where a TGT already exists from kinit; services use keytabs so they need no interactive login.
  • Your client fails with 'Server not found in Kerberos database.' What is the likely cause?
    sasl.kerberos.service.name or the broker hostname does not match the broker's actual principal kafka/<host>@REALM, so the requested service ticket name is wrong.

saying these in an interview costs you the question

  • Putting the password in plaintext instead of using a keytab for a service
  • Forgetting that sasl.kerberos.service.name must equal the service component of the broker principal
  • Assuming a jaas.conf file is still required when inline sasl.jaas.config works per-client

context

resolving links…