Added SASL/GSSAPI (Kerberos) authentication support

[kthimjo]

Summary

This PR adds GSSAPI/Kerberos authentication to kafka-backup-core, enabling
backup and restore operations against Kafka clusters secured with Kerberos, a
common requirement in enterprise environments. The implementation follows the
same always-compiled, configuration-driven pattern as the existing SCRAM and
PLAIN authentication methods: if sasl_mechanism is not set to GSSAPI, the
new code paths are never reached and behaviour is completely unchanged.

---

Motivation

Many organisations use Kerberos to secure their Kafka infrastructure.
kafka-backup previously supported PLAIN and SCRAM-SHA-256/512 but had no
path for Kerberos users, making it unusable in those environments without
workarounds. This change closes that gap.

---

Changes

New file: crates/kafka-backup-core/src/kafka/gssapi.rs

Implements the GssapiClient struct, which drives the two-phase Kafka
SASL/GSSAPI wire protocol (RFC 4752 §3.1):

• Phase 1 — GSS context establishment via one or more SaslAuthenticate
  round-trips until gss_init_sec_context signals completion.
• Phase 2 — Security-layer negotiation; always selects layer 0x01
  (no per-message wrapping), which is the only layer Kafka requires.

Uses libgssapi 0.9.1 — a safe Rust
binding over the OS GSSAPI library (libgssapi_krb5 on Linux, Heimdal on
macOS/BSD). No pure-Rust Kerberos implementation is used; all KDC
communication, ticket management, and keytab handling are delegated to the OS
library, which is the standard approach and is how the Java, Python, and
C Kafka clients work).

Modified: crates/kafka-backup-core/src/kafka/client.rs

• Added hostname: String field to BrokerConnection (extracted from the
  broker address at connect time) so the GSSAPI client can build the correct
  GSS target principal without re-parsing the address string.
• Added Gssapi arms to authenticate() and authenticate_raw(), passing the
  four GSSAPI parameters (service name, broker host, keytab path, krb5 config
  path) to the new GssapiClient.
• Added sasl_gssapi_auth() (uses send_request, for initial connections) and
  sasl_gssapi_auth_raw() (uses send_raw_request, for reconnects), mirroring
  the existing SCRAM method split that prevents async recursion.

Modified: crates/kafka-backup-core/src/config.rs

Added Gssapi variant to SaslMechanism and three new optional fields to
SecurityConfig:

Field	Type	Default	Description
sasl_kerberos_service_name	Option<String>	None → "kafka"	Must match broker's sasl.kerberos.service.name
sasl_keytab_path	Option<PathBuf>	None	Path to keytab; sets KRB5_CLIENT_KTNAME
sasl_krb5_config_path	Option<PathBuf>	None	Path to krb5.conf; sets KRB5_CONFIG

All three fields are optional. When None, the OS Kerberos library uses its
own resolution order ($KRB5_CLIENT_KTNAME / $KRB5_CONFIG env vars, then
/etc/krb5.conf, then the system credential cache). Existing configurations
that do not set these fields are completely unaffected.

Modified: crates/kafka-backup-core/src/kafka/mod.rs

Added mod gssapi;.

Modified: crates/kafka-backup-cli/src/commands/offset_reset.rs, offset_reset_bulk.rs, offset_rollback.rs

These files construct SecurityConfig struct literals by field name. The three
new fields were added explicitly as None to fix compilation. Full GSSAPI
support for the offset-reset commands (reading keytab/krb5 config from the
YAML or CLI flags) is left for a possible future PR (see Known limitations).

Modified: crates/kafka-backup-core/Cargo.toml

Added libgssapi = "0.9" as a regular (non-optional) dependency, consistent
with how ring is included regardless of which auth mechanism is configured.

---

Configuration

Below is a complete example for a SASL_SSL + GSSAPI setup. All three
GSSAPI-specific fields are optional.

source:                               # or `target:` for restore
  bootstrap_servers:
    - broker1.corp.com:6668
    - broker2.corp.com:6668
  security:
    security_protocol: SASL_SSL
    sasl_mechanism: GSSAPI

    # Must match sasl.kerberos.service.name on the broker (default: "kafka")
    sasl_kerberos_service_name: kafka

    # Path to a keytab file for unattended / service-account use.
    # Remove or comment out to use the OS credential cache (kinit).
    sasl_keytab_path: /etc/security/keytabs/kafka-backup.keytab

    # Path to a custom krb5.conf. Remove or comment out to use /etc/krb5.conf.
    sasl_krb5_config_path: /etc/kafka/krb5.conf

    # TLS CA certificate (required when security_protocol: SASL_SSL)
    ssl_ca_location: /var/ssl/private/ca.crt

Minimum viable config (relying on kinit/OS cache and system krb5.conf):

  security:
    security_protocol: SASL_SSL
    sasl_mechanism: GSSAPI
    ssl_ca_location: /var/ssl/private/ca.crt

---

Build requirements

The system GSSAPI development library must be present on the build host.
The runtime host needs only the runtime library (usually installed by default).

Distribution	Build	Runtime
RHEL / CentOS / Rocky	sudo dnf install krb5-devel	krb5-libs (default)
Debian / Ubuntu	sudo apt install libkrb5-dev	libkrb5-3 (default)
macOS (Homebrew)	brew install krb5 + set PKG_CONFIG_PATH	bundled

For CI (GitHub Actions Linux runner), add:

- name: Install Kerberos development libraries
  run: sudo apt-get install -y libkrb5-dev

---

Testing

Tested on Red Hat Enterprise Linux 9.7 (bare metal VM) against a
multi-broker Kafka cluster with SASL_SSL + GSSAPI:

Scenario	Result
kinit credential cache, no keytab config	✅
Keytab file via sasl_keytab_path, custom krb5.conf	✅
Keytab file via sasl_keytab_path, OS default krb5.conf	✅
Valid keytab, user not authorised on Kafka	✅ 0 topics backupped
Invalid / unreadable keytab, no ticket in cache	✅ clear error
Valid keytab, invalid krb5.conf path	✅ clear error
Backup operation end-to-end	✅
Restore operation end-to-end	✅
cargo test passed	✅

Testing in Docker / Kubernetes environments would be appreciated. A
docker-compose setup with a Kerberized Kafka and a KDC container would be a
valuable addition to the kafka-backup-demos repository.

---

Example log output

Successful authentication with keytab:

2026-04-20T21:36:23.802996Z DEBUG kafka_backup_core::kafka::gssapi: GSSAPI: KRB5_CONFIG=/etc/kafka/krb5.conf
2026-04-20T21:36:23.803055Z DEBUG kafka_backup_core::kafka::gssapi: GSSAPI: KRB5_CLIENT_KTNAME=/etc/security/keytabs/kafka-backup.keytab
2026-04-20T21:36:23.813211Z DEBUG kafka_backup_core::kafka::gssapi: GSSAPI: Phase 2 complete (server_layers=0x01, authz_id="")
2026-04-20T21:36:23.813724Z DEBUG kafka_backup_core::kafka::client: SASL GSSAPI authentication successful (broker: broker1.corp.com)

Invalid keytab with no ticket in the OS cache:

2026-04-20T21:31:38.105568Z WARN kafka_backup_core::health: Component kafka became Unhealthy:
  Some("Authentication error: GSSAPI: failed to acquire Kerberos credentials:
  No credentials were supplied, or the credentials were unavailable or inaccessible
  (No Kerberos credentials available (default cache: KCM:)).
  Check that either a valid ticket-granting ticket exists (run `kinit`) or that
  `sasl_keytab_path` in the security configuration points to a readable keytab file.")

---

Known limitations

• Offset-reset commands (offset-reset, offset-reset-bulk,
  offset-rollback) currently default all GSSAPI fields to None in their
  parse_security_config helper. These commands will work with kinit
  credential cache but do not yet read sasl_keytab_path or
  sasl_krb5_config_path from YAML or CLI flags. Could be the focus of
  a future PR.

• This implementation has only been tested on Linux (RHEL 9.7).

---

Checklist

• Code follows the existing style and conventions of the project
• New dependency (libgssapi 0.9) is justified and documented
• No breaking changes to existing authentication methods or configurations
• Behaviour is unchanged when sasl_mechanism is not GSSAPI
• Error messages are descriptive and guide the user toward a resolution
• Unit tests for gssapi.rs (a full Kerberos handshake test requires a live KDC; contributions welcome)
• Integration test in Docker / Kubernetes with a Kerberized Kafka
• Offset-reset commands: full GSSAPI support (potential future PR)

[sionsmith]

Thanks for tackling this — Kerberos is a known gap and the Phase 1 / Phase 2 state machine in gssapi.rs is solid work.

Heads-up that 0.14.0 (PR #94, currently in review) has since landed the SaslMechanismPlugin extension trait — a pluggable SASL dispatch path that was designed specifically to absorb mechanisms like GSSAPI, OAUTHBEARER, and MSK IAM without expanding the core enum or baking vendor-coupled deps into the default build. A few consequences for this PR as currently shaped:

1. Merge conflict is structural, not textual. authenticate_raw() no longer exists on the post-0.14 branch — reconnect and initial-connect share a single dispatch function. The enum-plus-match-arm approach here doesn't have a place to hook in.
2. libgssapi as an always-compiled dep forces libkrb5-dev / krb5-devel / brew install krb5 onto every CI runner, every release build, and every dev machine — for a feature the majority of users will never touch. A gssapi Cargo feature gate (default off) preserves the lean build.
3. KIP-368 re-auth is live in 0.14.0. A plugin-shaped GSSAPI impl gets ticket refresh for free (broker's advertised session_lifetime_ms drives a scheduler that calls reauth_payload at ~80 % of the window). Your state machine already does a fresh gss_init_sec_context — the reauth surface fits naturally.
4. unsafe { std::env::set_var(KRB5_CONFIG, …) } races other connects in a multi-client process. Process-wide serialisation during credential acquisition (or upstreaming a keytab-aware Cred::acquire) closes that gap.

Proposal. Rework as a GssapiPlugin: SaslMechanismPlugin under crates/kafka-backup-core/src/kafka/sasl/gssapi.rs, gated by a gssapi Cargo feature. ~90 % of the state machine you've written transfers verbatim — the Phase 1 round-driver, Phase 2 layer negotiation, and wrap/unwrap are exactly what the trait wants.

I've prototyped this on feat/gssapi-plugin (stacked on feat/sasl-mechanism-plugin, six commits: feature scaffolding → config surface → plugin → CLI wiring → Docker KDC E2E fixture → docs). Happy to pair with you on porting your logic across, or you're welcome to pick it up and drive to completion yourself — the skeleton's there. See docs/PRD-sasl-mechanism-plugin.md and examples/custom_sasl_plugin.rs in PR #94 for the trait contract.

Credit for the Phase 1/2 state machine stays yours either way.

[kthimjo]

Hi Sion, thank you for the quick feedback, I appreciate it. My mistake for not being aware that draft PR #94 was created before this.
Your proposal makes perfect sense, I will look into your prototype and try to fit the GssapiClient into it in the next few days.