> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SASL Authentication

> Configure SASL_PLAINTEXT or SASL_SSL authentication for AutoMQ Kafka clients.

AutoMQ supports SASL authentication with Kafka ACL users. Use `SASL_PLAINTEXT` only on a trusted private network. Use `SASL_SSL` to encrypt client traffic with TLS.

## Enable SASL\_PLAINTEXT

### Server configuration

When you create the instance, enable SASL authentication and the `SASL_PLAINTEXT` listener. Create an ACL user and grant only the Topic and Consumer Group permissions required by the application.

### Client configuration

Configure the Kafka client with the credentials created in AutoMQ. The following example uses SASL/PLAIN:

```properties theme={null}
bootstrap.servers=<sasl-plaintext-bootstrap-server>
security.protocol=SASL_PLAINTEXT
sasl.mechanism=PLAIN
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="<username>" password="<password>";
```

## Enable SASL\_SSL

`SASL_SSL` combines SASL client authentication with TLS server authentication and transport encryption. Server certificate responsibilities depend on the DNS Zone mode selected when the instance is created.

| DNS Zone mode | Server certificate responsibility | User-provided server TLS material |
| - | - | - |
| AutoMQ Managed Public DNS Zone | AutoMQ provides and manages the authoritative server certificate for the instance endpoint. | None. Do not upload a self-signed CA, Server Certificate, or Private Key. |
| Customer-managed Private DNS Zone | You provide and rotate a server certificate whose Subject Alternative Name matches the private endpoint domain. | Server CA certificate, Server Certificate, and Private Key. |

> [!NOTE]
>
> Select the DNS Zone mode and enable `SASL_SSL` when you create the instance. Existing instances cannot be changed from an unencrypted listener to `SASL_SSL`.

### Use an AutoMQ Managed Public DNS Zone

1. When creating the instance, select **Public DNS Zone** and the AutoMQ managed mode.
2. Enable the `SASL_SSL` listener and configure SASL authentication.
3. Do not upload user-managed server certificate files. AutoMQ provisions and renews the server certificate.
4. Create an ACL user and grant the required resource permissions.

Because the server certificate is issued by a public certificate authority, Kafka clients normally use the trust anchors supplied by the operating system or Java runtime. Do not configure a custom truststore unless your organization requires one.

```properties theme={null}
bootstrap.servers=<sasl-ssl-bootstrap-server>
security.protocol=SASL_SSL
sasl.mechanism=PLAIN
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="<username>" password="<password>";
```

### Use a customer-managed Private DNS Zone

For a customer-managed Private DNS Zone, you must provide a CA certificate, Server Certificate, and Server Private Key. Use certificates issued by your organization's certificate authority when available. If you need to create and maintain a private CA, use the following procedure as a reference.

> [!WARNING]
>
> The following commands create a private CA. Protect `ca.key` and `server.key` according to your organization's key management requirements. Do not upload the CA private key to AutoMQ or distribute either private key to Kafka clients.

#### 1. Create a private CA

Create `ca.cnf`. Replace the distinguished-name values before running the commands.

```ini theme={null}
[ req ]
prompt = no
distinguished_name = distinguished_name
x509_extensions = extensions

[ distinguished_name ]
organizationName = <organization-name>
commonName = <private-ca-common-name>

[ extensions ]
basicConstraints = critical,CA:true,pathlen:1
keyUsage = critical,keyCertSign,cRLSign
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
```

Generate the CA private key and CA certificate:

```bash theme={null}
openssl genrsa -out ca.key 2048
chmod 400 ca.key
openssl req -new -x509 \
  -config ca.cnf \
  -key ca.key \
  -days 3650 \
  -out ca.crt
```

#### 2. Issue the Server Certificate

Create `server.cnf`. The Subject Alternative Name (SAN) must cover the AutoMQ private endpoint names associated with the Private DNS Zone. Use the exact DNS name or wildcard required by the instance endpoint. Do not rely on the Common Name for hostname verification.

```ini theme={null}
[ req ]
prompt = no
distinguished_name = distinguished_name
req_extensions = extensions

[ distinguished_name ]
organizationName = <organization-name>
commonName = <server-common-name>

[ extensions ]
basicConstraints = critical,CA:false
keyUsage = critical,digitalSignature,keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[ alt_names ]
DNS.1 = <private-endpoint-dns-name-or-wildcard>
```

Generate the Server Private Key and certificate signing request (CSR), and then sign the CSR with the private CA:

```bash theme={null}
openssl genrsa -out server.key 2048
chmod 400 server.key
openssl req -new \
  -config server.cnf \
  -key server.key \
  -out server.csr
openssl x509 -req \
  -in server.csr \
  -CA ca.crt \
  -CAkey ca.key \
  -CAcreateserial \
  -days 365 \
  -extfile server.cnf \
  -extensions extensions \
  -out server.crt
```

Verify the certificate SAN and validity period before uploading it:

```bash theme={null}
openssl x509 -in server.crt -noout -subject -issuer -dates -ext subjectAltName
```

#### 3. Configure AutoMQ

1. When creating the instance, select the customer-managed **Private DNS Zone** and enable the `SASL_SSL` listener.
2. Upload `ca.crt` as the Server CA certificate, `server.crt` as the Server Certificate, and `server.key` as the Private Key.
3. Create an ACL user and grant only the Topic and Consumer Group permissions required by the application.

#### 4. Configure a Kafka client

Import `ca.crt` into the client truststore when the client runtime does not already trust the private CA:

```bash theme={null}
keytool -importcert \
  -alias automq-server-ca \
  -file ca.crt \
  -keystore truststore.jks \
  -storepass <truststore-password>
```

```properties theme={null}
bootstrap.servers=<sasl-ssl-bootstrap-server>
security.protocol=SASL_SSL
sasl.mechanism=PLAIN
sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="<username>" password="<password>";
ssl.truststore.type=JKS
ssl.truststore.location=/path/to/truststore.jks
ssl.truststore.password=<truststore-password>
```

## Certificate expiration responsibility

* **AutoMQ Managed Public DNS Zone:** AutoMQ monitors and renews the server certificate. You do not rotate the server certificate.
* **Customer-managed Private DNS Zone:** You are responsible for monitoring and rotating the server CA and certificate before expiration. Use `kafka_stream_cert_expiry_timestamp_milliseconds` and `kafka_stream_cert_days_remaining` to monitor the installed server certificate. For collection methods, see [Monitoring and Alerting with Prometheus](/automq-cloud/monitoring-alert/monitoring-alert-via-prometheus).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.