消息队列 / 系统课时
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 中配置:
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 写入:
bin/kafka-acls.sh \
--bootstrap-server localhost:9093 \
--command-config admin.properties \
--add \
--allow-principal User:orders-producer \
--operation Write \
--topic orders预期输出:
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:
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预期输出:
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:
bin/kafka-acls.sh \
--bootstrap-server localhost:9093 \
--command-config admin.properties \
--add \
--allow-principal User:orders-producer \
--operation IdempotentWrite \
--cluster预期输出:
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 权限限制到该标识或受控前缀:
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预期输出:
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:
bin/kafka-acls.sh \
--bootstrap-server localhost:9093 \
--command-config admin.properties \
--list \
--topic orders预期输出:
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 规则。最小权限的目标不是“命令能跑就行”,而是让每个业务身份只拥有完成职责所需的资源和操作。