SASL Authentication

Pilot supports all standard Kafka SASL mechanisms for authenticating with brokers.

Supported Mechanisms

Mechanism	Protocol	Description
`PLAIN`	`SASL_PLAINTEXT` or `SASL_SSL`	Username/password in plaintext (use with SSL)
`SCRAM-SHA-256`	`SASL_PLAINTEXT` or `SASL_SSL`	Salted challenge-response (recommended)
`SCRAM-SHA-512`	`SASL_PLAINTEXT` or `SASL_SSL`	Stronger SCRAM variant
`GSSAPI`	`SASL_PLAINTEXT` or `SASL_SSL`	Kerberos authentication
`OAUTHBEARER`	`SASL_PLAINTEXT` or `SASL_SSL`	OAuth 2.0 / OIDC token-based auth

PLAIN


KAFKA_SECURITY_PROTOCOL=SASL_PLAINTEXT
KAFKA_SASL_MECHANISM=PLAIN
KAFKA_SASL_USERNAME=pilot
KAFKA_SASL_PASSWORD=pilot-secret

Note: PLAIN sends credentials in cleartext. Always combine with SSL in production: KAFKA_SECURITY_PROTOCOL=SASL_SSL.

SCRAM-SHA-256 / SCRAM-SHA-512


KAFKA_SECURITY_PROTOCOL=SASL_SSL
KAFKA_SASL_MECHANISM=SCRAM-SHA-256
KAFKA_SASL_USERNAME=pilot
KAFKA_SASL_PASSWORD=pilot-secret
KAFKA_SSL_CA_CERT_FILE=/certs/ca.pem

For SCRAM-SHA-512, change the mechanism:


KAFKA_SASL_MECHANISM=SCRAM-SHA-512

SCRAM is the recommended mechanism for username/password authentication as credentials are never sent in plaintext. Pilot runs the SCRAM exchange (RFC 5802 and RFC 7677) with the hash of the chosen mechanism; the broker must have the user’s credentials for that mechanism (kafka-configs --alter --add-config 'SCRAM-SHA-256=[password=...]' --entity-type users --entity-name pilot).

GSSAPI (Kerberos)


KAFKA_SECURITY_PROTOCOL=SASL_PLAINTEXT
KAFKA_SASL_MECHANISM=GSSAPI
KAFKA_SASL_KERBEROS_REALM=EXAMPLE.COM
KAFKA_SASL_KERBEROS_SERVICE_NAME=kafka
KAFKA_SASL_KERBEROS_USERNAME=[email protected]
KAFKA_SASL_KERBEROS_KEYTAB_FILE=/etc/security/keytabs/pilot.keytab
KAFKA_SASL_KERBEROS_CONFIG_FILE=/etc/krb5.conf

Alternatively, use a password instead of a keytab:


KAFKA_SASL_KERBEROS_PASSWORD=kerberos-password

Docker Volume Mounts


services:
  pilot:
    image: calinora/pilot:latest
    volumes:
      - ./keytabs/pilot.keytab:/etc/security/keytabs/pilot.keytab:ro
      - ./krb5.conf:/etc/krb5.conf:ro
    environment:
      KAFKA_SECURITY_PROTOCOL: SASL_PLAINTEXT
      KAFKA_SASL_MECHANISM: GSSAPI
      KAFKA_SASL_KERBEROS_REALM: EXAMPLE.COM
      KAFKA_SASL_KERBEROS_SERVICE_NAME: kafka
      KAFKA_SASL_KERBEROS_USERNAME: [email protected]
      KAFKA_SASL_KERBEROS_KEYTAB_FILE: /etc/security/keytabs/pilot.keytab
      KAFKA_SASL_KERBEROS_CONFIG_FILE: /etc/krb5.conf

OAUTHBEARER

For OAuth/OIDC-based Kafka authentication. See OAuth for Kafka for detailed configuration.


KAFKA_SECURITY_PROTOCOL=SASL_SSL
KAFKA_SASL_MECHANISM=OAUTHBEARER
KAFKA_SASL_OAUTH_TOKEN_ENDPOINT_URL=https://auth.example.com/oauth/token
KAFKA_SASL_OAUTH_CLIENT_ID=pilot-client
KAFKA_SASL_OAUTH_CLIENT_SECRET=client-secret
KAFKA_SASL_OAUTH_SCOPE=kafka

The HTTPS client that fetches tokens from KAFKA_SASL_OAUTH_TOKEN_ENDPOINT_URL trusts the system roots plus the CA given by KAFKA_SSL_CA_CERT_FILE or KAFKA_SSL_CA_CERT_PEM, so a token endpoint signed by the same private CA as the brokers needs no extra configuration. KAFKA_SSL_INSECURE_SKIP_VERIFY=true disables verification for the token endpoint as well as for the brokers. See Token Endpoint TLS.

Environment Variables Reference

Variable	Default	Description
`KAFKA_SECURITY_PROTOCOL`	`PLAINTEXT`	`PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, `SASL_SSL`
`KAFKA_SASL_MECHANISM`	`PLAIN`	`PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`, `GSSAPI`, `OAUTHBEARER`
`KAFKA_SASL_USERNAME`	`""`	Username for PLAIN/SCRAM
`KAFKA_SASL_PASSWORD`	`""`	Password for PLAIN/SCRAM
`KAFKA_SASL_KERBEROS_REALM`	`""`	Kerberos realm
`KAFKA_SASL_KERBEROS_SERVICE_NAME`	`kafka`	Kerberos service name
`KAFKA_SASL_KERBEROS_USERNAME`	`""`	Kerberos principal
`KAFKA_SASL_KERBEROS_PASSWORD`	`""`	Kerberos password
`KAFKA_SASL_KERBEROS_KEYTAB_FILE`	`""`	Kerberos keytab file path
`KAFKA_SASL_KERBEROS_CONFIG_FILE`	`""`	Kerberos config file path