消息队列 / 系统课时

ACL 权限控制

ACL 权限控制

Kafka ACL 负责回答“已认证的用户能做什么”。本课从最小权限出发,为生产者、消费者和事务客户端分别配置 Topic、Group、Cluster 与 TransactionalId 权限,并通过授权失败信息定位缺失的资源与操作。

学习目标

  • 理解 ACL 中 Principal、Resource、Operation 与 Permission 的匹配关系
  • 按生产、消费和事务场景授予最小权限
  • 使用 ACL 查询与客户端报错定位常见授权失败

先理解 ACL 的匹配维度

一条 ACL 可以理解为“谁,对什么资源,允许或拒绝什么操作”。常见资源包括 Topic、Group、Cluster 和 TransactionalId。例如,消费者通常同时需要 Topic 的 Read 与消费组的 Read;只给 Topic 权限,仍可能在加入组时失败。

KRaft 集群通常使用 org.apache.kafka.metadata.authorizer.StandardAuthorizer。Broker 端若尚未启用 Authorizer,可在 server.properties 中配置:

properties
authorizer.class.name=org.apache.kafka.metadata.authorizer.StandardAuthorizer
super.users=User:admin

该配置需要重启相应 Broker/Controller 进程后生效。验证方法是使用管理员身份运行 kafka-acls.sh --list;若 Authorizer 已启用且连接参数正确,命令会返回现有 ACL,而不是报 Authorizer 未配置或认证失败。

为生产者和消费者授予最小权限

假设生产者身份为 User:orders-producer,只允许向 orders Topic 写入:

bash
bin/kafka-acls.sh \
  --bootstrap-server localhost:9093 \
  --command-config admin.properties \
  --add \
  --allow-principal User:orders-producer \
  --operation Write \
  --topic orders

预期输出:

text
Adding ACLs for resource `ResourcePattern(resourceType=TOPIC, name=orders, patternType=LITERAL)`:
  (principal=User:orders-producer, host=*, operation=WRITE, permissionType=ALLOW)

Current ACLs for resource `ResourcePattern(resourceType=TOPIC, name=orders, patternType=LITERAL)`:
  (principal=User:orders-producer, host=*, operation=WRITE, permissionType=ALLOW)

消费者身份为 User:orders-consumer,既要读 Topic,也要加入消费组 orders-cg。分别添加两条 ACL:

bash
bin/kafka-acls.sh \
  --bootstrap-server localhost:9093 \
  --command-config admin.properties \
  --add \
  --allow-principal User:orders-consumer \
  --operation Read \
  --topic orders

bin/kafka-acls.sh \
  --bootstrap-server localhost:9093 \
  --command-config admin.properties \
  --add \
  --allow-principal User:orders-consumer \
  --operation Read \
  --group orders-cg

预期输出:

text
Adding ACLs for resource `ResourcePattern(resourceType=TOPIC, name=orders, patternType=LITERAL)`:
  (principal=User:orders-consumer, host=*, operation=READ, permissionType=ALLOW)

Adding ACLs for resource `ResourcePattern(resourceType=GROUP, name=orders-cg, patternType=LITERAL)`:
  (principal=User:orders-consumer, host=*, operation=READ, permissionType=ALLOW)

不同 Kafka 版本可能在随后附加 Current ACLs 列表,但核心验证点是 Topic 与 Group 两个资源都存在对应的 ALLOW READ。

处理 Cluster 与 TransactionalId 权限

Cluster 级权限不要因为省事就授予业务账号 All。例如,客户端确实需要集群级幂等写权限时,应只授予 IdempotentWrite:

bash
bin/kafka-acls.sh \
  --bootstrap-server localhost:9093 \
  --command-config admin.properties \
  --add \
  --allow-principal User:orders-producer \
  --operation IdempotentWrite \
  --cluster

预期输出:

text
Adding ACLs for resource `ResourcePattern(resourceType=CLUSTER, name=kafka-cluster, patternType=LITERAL)`:
  (principal=User:orders-producer, host=*, operation=IDEMPOTENT_WRITE, permissionType=ALLOW)

事务生产者还会使用 transactional.id。若应用配置为 transactional.id=orders-tx-01,应把 TransactionalId 权限限制到该标识或受控前缀:

bash
bin/kafka-acls.sh \
  --bootstrap-server localhost:9093 \
  --command-config admin.properties \
  --add \
  --allow-principal User:orders-producer \
  --operation Write \
  --transactional-id orders-tx-01

预期输出:

text
Adding ACLs for resource `ResourcePattern(resourceType=TRANSACTIONAL_ID, name=orders-tx-01, patternType=LITERAL)`:
  (principal=User:orders-producer, host=*, operation=WRITE, permissionType=ALLOW)

Topic 的 Write、Cluster 的 IdempotentWrite 与 TransactionalId 的 Write 解决的是不同授权检查,不能相互替代。是否需要某项权限应以客户端实际功能和所用 Kafka 版本的授权检查为准,不要预先给出超范围权限。

查询 ACL 并定位授权失败

配置完成后,用管理员连接列出目标 Topic 的 ACL:

bash
bin/kafka-acls.sh \
  --bootstrap-server localhost:9093 \
  --command-config admin.properties \
  --list \
  --topic orders

预期输出:

text
Current ACLs for resource `ResourcePattern(resourceType=TOPIC, name=orders, patternType=LITERAL)`:
  (principal=User:orders-producer, host=*, operation=WRITE, permissionType=ALLOW)
  (principal=User:orders-consumer, host=*, operation=READ, permissionType=ALLOW)

客户端若出现 TopicAuthorizationException,先检查 Topic 权限;出现 GroupAuthorizationException,检查 Group;事务初始化时报 TransactionalId 授权错误,则检查 transactional.id 与 ACL 的名称或前缀是否匹配。若报错发生在认证阶段,则 ACL 还没有参与,应先修复 SASL/TLS。

ACL 排查时还要确认 Principal 是否与认证结果完全一致,例如 User:orders-consumer 与 User:orders_consumer 是两个不同身份。最后再检查资源模式:LITERAL 只匹配精确名称,批量 Topic 更适合有边界的 PREFIXED 规则。最小权限的目标不是“命令能跑就行”,而是让每个业务身份只拥有完成职责所需的资源和操作。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

ACL 权限控制

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通