> ## 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 身份验证

> 为 AutoMQ Kafka 客户端配置 SASL_PLAINTEXT 或 SASL_SSL 身份验证。

AutoMQ 支持使用 Kafka ACL 用户进行 SASL 身份验证。仅在可信私有网络中使用 `SASL_PLAINTEXT`；使用 `SASL_SSL` 可通过 TLS 加密客户端流量。

## 开启 SASL\_PLAINTEXT

### 服务端配置

创建实例时启用 SASL 身份验证和 `SASL_PLAINTEXT` Listener。创建 ACL 用户，并仅授予应用所需的 Topic 和 Consumer Group 权限。

### 客户端配置

使用 AutoMQ 中创建的凭证配置 Kafka 客户端。以下示例使用 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>";
```

## 开启 SASL\_SSL

`SASL_SSL` 同时提供 SASL 客户端身份验证、TLS 服务端身份验证和传输加密。服务端证书责任取决于创建实例时选择的 DNS Zone 模式。

| DNS Zone 模式                    | 服务端证书责任                                    | 用户提供的服务端 TLS 材料                                         |
| ------------------------------ | ------------------------------------------ | ------------------------------------------------------- |
| AutoMQ Managed Public DNS Zone | AutoMQ 为实例接入地址提供并管理 Server 权威证书。           | 无。不要上传自签 CA、Server Certificate 或 Private Key。           |
| 用户管理的 Private DNS Zone         | 用户提供并轮转 SAN 与私有接入域名匹配的 Server Certificate。 | Server CA Certificate、Server Certificate 和 Private Key。 |

<Note>
  创建实例时需要选择 DNS Zone 模式并启用 `SASL_SSL`。现有实例不能从未加密 Listener 变更为 `SASL_SSL`。
</Note>

### 使用 AutoMQ Managed Public DNS Zone

1. 创建实例时选择 **Public DNS Zone** 和 AutoMQ Managed 模式。
2. 启用 `SASL_SSL` Listener 并配置 SASL 身份验证。
3. 不要上传用户管理的服务端证书文件。AutoMQ 会签发并续期 Server Certificate。
4. 创建 ACL 用户并授予所需资源权限。

Server Certificate 由公共 CA 签发，因此 Kafka 客户端通常使用操作系统或 Java 运行时提供的信任锚。除非组织安全策略另有要求，否则无需配置自定义 Truststore。

```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>";
```

### 使用用户管理的 Private DNS Zone

使用用户管理的 Private DNS Zone 时，用户必须提供 CA Certificate、Server Certificate 和 Server Private Key。优先使用组织证书颁发机构签发的证书。如果需要自行创建和维护私有 CA，可参考以下步骤。

<Warning>
  以下命令会创建私有 CA。请按照组织的密钥管理要求保护 `ca.key` 和 `server.key`。不要将 CA Private Key 上传到 AutoMQ，也不要将任何私钥分发给 Kafka 客户端。
</Warning>

#### 1. 创建私有 CA

创建 `ca.cnf`，执行命令前替换证书主题信息。

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

生成 CA Private Key 和 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. 签发 Server Certificate

创建 `server.cnf`。Subject Alternative Name（SAN）必须覆盖与 Private DNS Zone 关联的 AutoMQ 私有接入域名。请根据实例接入地址使用准确域名或所需的通配符域名，不要依赖 Common Name 完成主机名验证。

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

生成 Server Private Key 和证书签名请求（CSR），然后使用私有 CA 签发 Server Certificate：

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

上传前检查证书的 SAN 和有效期：

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

#### 3. 配置 AutoMQ

1. 创建实例时选择用户管理的 **Private DNS Zone**，并启用 `SASL_SSL` Listener。
2. 将 `ca.crt` 作为 Server CA Certificate、`server.crt` 作为 Server Certificate、`server.key` 作为 Private Key 上传。
3. 创建 ACL 用户，并仅授予应用所需的 Topic 和 Consumer Group 权限。

#### 4. 配置 Kafka 客户端

如果客户端运行时默认不信任该私有 CA，将 `ca.crt` 导入客户端 Truststore：

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

## 证书过期责任

* **AutoMQ Managed Public DNS Zone：** AutoMQ 监控并续期 Server Certificate，用户无需轮转服务端证书。
* **用户管理的 Private DNS Zone：** 用户负责在 Server CA 和 Server Certificate 过期前完成监控和轮转。可使用 `kafka_stream_cert_expiry_timestamp_milliseconds` 和 `kafka_stream_cert_days_remaining` 监控已安装的服务端证书。采集方法请参见 [Prometheus 监控与告警](/zh/automq-cloud/monitoring-alert/monitoring-alert-via-prometheus)。