> ## 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.

# 管理 ACL

> Enable and manage Kafka ACL in AutoMQ for cloud-native scalability and cost-efficient, secure access. AutoMQ offers seamless Kafka compatibility and fine-grained authorization.

本文介绍 Kafka ACL 功能的基本概念、相关约束以及如何在 AutoMQ 实例中开启并使用 ACL 功能。

## Kafka ACL 概念

### 概述

Apache Kafka 提供 ACL 功能，支持 Kafka 客户端进行身份校验和权限验证。AutoMQ 100% 兼容 Apache Kafka，因此使用 AutoMQ 实例时可以开启并使用 Kafka ACL 功能。

<Tip>
  使用 Kafka ACL 需注意如下约束：

  **版本约束：** 需要确保 AutoMQ 实例版本>= 1.10.x，否则需要先升级版本再开启。

  **可选开启：** AutoMQ 实例默认没有开启 ACL，用户可在创建实例或后续，手工开启 ACL。

  **访问协议：** AutoMQ 仅支持通过 VPC 内网 SASL\_PLAINTEXT、SASL\_SSL 和 mTLS 协议访问集群。

  **资源类型：** AutoMQ 当前支持 Kafka Cluster、Topic、Consumer Group、Transaction ID 类型的资源进行 ACL 权限控制，不支持 DelegationToken 类型。如有需求，请参考[获取人工服务▸](/zh/automq-cloud/support/obtaining-services)联系我们。
</Tip>

### ACL 用户

在 Kafka ACL 功能里，用户是 ACL 进行身份识别的主体。Kafka 客户端通过访问协议透传自己的用户标识，Kafka 服务端进行身份识别并确认当前客户端请求对应的用户，然后进行后续的权限验证等操作。

需要注意 Kafka ACL 用户和 AutoMQ 环境成员的区别：

| **场景对比**<br /> | **Kafka ACL 用户**<br />     | **AutoMQ 环境成员**<br />  |
| -------------- | -------------------------- | ---------------------- |
| **使用场景**<br /> | Kafka 客户端 API、CLI 访问<br /> | AutoMQ 环境 Web 访问<br /> |
| **覆盖范围**<br /> | 作用于单个 Kafka 实例<br />       | 作用于整个环境，可以跨实例操作<br />  |

<Tip>
  **注意** ：

  当使用 mTLS 协议访问 AutoMQ 实例时，服务端会默认将客户端证书的身份映射到 ACL 用户。映射规则默认设置为 RULE:.\*CN=(\[^,]+).\*/\$1/。

  举例：客户端证书身份信息为：*CN=user01,O=xxxx,OU=xxx,L=xxx,S=xxx,C=xxx*

  则 AutoMQ 提取 CN 字段，并拼接出 Principal= User:user01。
</Tip>

### ACL 授权策略

Apache Kafka 通过授权策略定义不同的用户可以访问的资源范围以及对应可以执行的操作列表。参考 Apache Kafka 的[设计文档](https://kafka.apache.org/documentation/#security_authz)。AutoMQ 实例的授权策略包含如下信息：

| **参数**<br />   | **取值说明**<br />                                                                                                                                                                                                                                                               |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **资源类型**<br /> | <ul><li>说明：资源类型是指 Kafka ACL 策略适用的 Kafka 资源的类别，当前支持如下类型：</li><ul><li>Cluster：定义实例（集群）粒度的操作权限，例如查看集群配置，查看云信息。</li><li>Topic：定义 Topic 粒度的操作权限，例如删除、订阅、发送消息等权限。</li><li>Cosumer Group：定义 Kafka Consumer 客户端加入 Group 并参与收消息的权限。</li><li>TransactionID：定义事务消息的使用权限。</li></ul></ul> |
| **资源名称**<br /> | <ul><li>说明：资源名称是定义 ACL 策略覆盖的资源范围，通过设置自定义字符串约定，可以是精确的名称或者是前缀。</li><li>限制：参考[使用限制▸](/zh/automq-cloud/overview/restrictions) 。</li></ul>                                                                                                                                        |
| **匹配类型**<br /> | <ul><li>说明：匹配类型用于描述当前 ACL 规则中资源名称字段是否为精确匹配还是前缀匹配。</li><li>类型：</li><ul><li>literal：精确匹配，即资源名称就是实际生效的名称。</li><li>prefixed：前缀匹配，即资源名称为实际生效的资源的前缀。</li></ul></ul>                                                                                                                |
| **操作组**<br />  | <ul><li>说明：操作组是 AutoMQ 对 Apache Kafka 细粒度原子授权操作（Operation）的封装组合。每个操作组内包含多个 Kafka 操作。通过操作组可以简化一系列典型使用场景的授权过程。</li><li>关于操作组和 Kafka ACL 操作的映射关系参考下方表格。</li></ul>                                                                                                               |
| **授权类型**<br /> | <ul><li>说明：Apache Kafka ACL 支持以下两种授权类型：</li><ul><li>ALLOW：该 ACL 策略允许用户执行上述关联资源的操作。</li><li>DENY：该 ACL 策略拒绝用户执行上述关联资源的操作。</li></ul></ul><Tip><br />注意：DENY 类型授权策略类似黑名单能力，具备排他特性，优先级高于 ALLOW。<br /></Tip><br />                                                                |
| **访问来源**<br /> | <ul><li>说明：访问来源定义了当前 ACL 策略仅针对当前 IP 访问来源时生效。对于没有命中的 IP 访问来源不生效。</li><li>限制：访问来源仅支持精确的 IP 地址，不支持 CIDR 网段以及域名。</li></ul>                                                                                                                                                       |

AutoMQ 定义了操作组用于简化授权操作，其中操作组和 Kafka 操作的映射关系如下表：

<table>
  <thead>
    <tr>
      <th colspan="1" rowspan="1">
        资源类型

        <br />
      </th>

      <th colspan="1" rowspan="1">
        操作组

        <br />
      </th>

      <th colspan="1" rowspan="1">
        包含的操作

        <br />
      </th>

      <th colspan="1" rowspan="1">
        推荐场景

        <br />
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td colspan="1" rowspan="1">
        Cluster

        <br />
      </td>

      <td colspan="1" rowspan="1">
        All

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>Alter</li>

          <li>AlterConfigs</li>

          <li>ClusterAction</li>

          <li>Create</li>

          <li>Describe</li>

          <li>DescribeConfigs</li>

          <li>All</li>
        </ul>
      </td>

      <td colspan="1" rowspan="1">
        All 操作组约定了对 Kafka 集群（实例）全部的操作权限。一般推荐授权给 Kafka UI、CLI 工具类的用户身份。

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="3">
        Topic

        <br />
      </td>

      <td colspan="1" rowspan="1">
        All

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>Alter</li>

          <li>AlterConfigs</li>

          <li>Create</li>

          <li>Delete</li>

          <li>Describe</li>

          <li>DescribeConfigs</li>

          <li>Read</li>

          <li>Write</li>
        </ul>
      </td>

      <td colspan="1" rowspan="1">
        All 操作组约定了对单个 Topic 所有的操作权限。一般推荐授权给既需要生产权限、又需要订阅权限的用户身份。

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        Produce

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>Create</li>

          <li>Write</li>

          <li>Describe</li>
        </ul>
      </td>

      <td colspan="1" rowspan="1">
        Produce 操作组约定了对单个 Topic 生产消息的最小操作范围。推荐授权给消息生产的用户身份。

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        Consume

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>Read</li>

          <li>Describe</li>
        </ul>
      </td>

      <td colspan="1" rowspan="1">
        Consume 操作组约定了对单个 Topic 订阅消息的最小操作范围。推荐授权给消息订阅的用户身份。

        <br />

        <Tip>
          <br />

          如需使用 Consumer Group 订阅消息，除授权 Topic 的 Consume 操作组，还需要对目标 Consumer Group 进行授权。

          <br />
        </Tip>

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        Consumer Group

        <br />
      </td>

      <td colspan="1" rowspan="1">
        All

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>Delete</li>

          <li>Describe</li>

          <li>Read</li>
        </ul>
      </td>

      <td colspan="1" rowspan="1">
        All 操作组约定了使用特定 Consumer Group 的所有操作权限。推荐授权给消息订阅的用户身份。

        <br />

        <Tip>
          <br />

          如需使用 Consumer Group 订阅消息，除了授权 Consumer Group ，还需要对目标 Topic 授予 Consume 操作组权限。

          <br />
        </Tip>

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        TransactionID

        <br />
      </td>

      <td colspan="1" rowspan="1">
        All

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>Describe</li>

          <li>Write</li>
        </ul>
      </td>

      <td colspan="1" rowspan="1">
        All 操作组约定了针对特定 TransactionID 允许读取状态和提交事务的操作权限。推荐授权给需要发送事务消息的用户身份。

        <br />
      </td>
    </tr>
  </tbody>
</table>

## 使用 Kafka ACL

在 AutoMQ 实例中使用 Kafka ACL 功能，参考如下流程：

<img src="https://mintcdn.com/automq/fL62XJ-sjry0eTzF/zh/automq-cloud/manage-security/manage-kafka-acls/1.webp?fit=max&auto=format&n=fL62XJ-sjry0eTzF&q=85&s=944d5bfc7dd6147ee2cb651002fe6d66" width="2560" height="480" data-path="zh/automq-cloud/manage-security/manage-kafka-acls/1.webp" />

需要注意的是：

* 创建实例时，默认没有开启 ACL，此时客户端通过 PLAINTEXT 协议，匿名访问集群，拥有所有操作的权限。

* 开启 ACL 后，PLAINTEXT 协议仍然提供服务，但应该立即切换所有的客户端应用，使用支持身份识别和权限验证的 SASL\_PLAINTEXT 接入点，防止未授权访问。切换完成后，关闭 PLAINTEXT 协议接入点。