---
title: "SASL Authentication - Pilot Docs"
description: "Configure SASL authentication for Kafka connections"
url: "https://docs.calinora.io/configuration/sasl/"
---

# 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

```bash
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

```bash
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:

```bash
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)

```bash
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=pilot@EXAMPLE.COM
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:

```bash
KAFKA_SASL_KERBEROS_PASSWORD=kerberos-password
```

### Docker Volume Mounts

```yaml
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: pilot@EXAMPLE.COM
      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](https://docs.calinora.io/configuration/oauth/) for detailed configuration.

```bash
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](https://docs.calinora.io/configuration/oauth/#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 |