访问控制
1. 访问控制功能介绍
访问控制（ACL）主要为 RocketMQ 提供 Topic 资源级别的高级访问控制功能。使用 RocketMQ 访问控制时，用户可以将用户名和密码参数注入到客户端以实现签名，服务器可以通过访问控制参数实现对各种资源的权限管理和验证。
ACL 控制在增强集群访问控制安全性的同时，会增加部署过程和运维管理的复杂性。通常仅建议在网络环境不安全、业务数据敏感以及多部门和多租户混用的场景下使用。如果生产集群本身是私有集群且不受外部部门和租户访问，则可以关闭此功能。
2. 访问控制的定义和属性值
2.1 权限定义
RocketMQ Topic 资源的访问控制定义主要如下表所示，分为以下四类
| 权限 | 定义 |
|---|---|
| DENY | 拒绝 |
| ANY | PUB 或 SUB 权限 |
| PUB | 发送权限 |
| SUB | 订阅权限 |
2.2 权限定义的关键属性
| 字段 | 值 | 定义 |
|---|---|---|
| globalWhiteRemoteAddresses | *;192.168.*.*;192.168.0.1 | 全局 IP 白名单 |
| accessKey | 字符串 | 访问密钥 |
| secretKey | 字符串 | 秘钥 |
| whiteRemoteAddress | *;192.168.*.*;192.168.0.1 | 用户 IP 白名单 |
| admin | true;false | 是否为管理员账户 |
| defaultTopicPerm | DENY;PUB;SUB;PUB|SUB | 默认 Topic 权限 |
| defaultGroupPerm | DENY;PUB;SUB;PUB|SUB | 默认 ConsumerGroup 权限 |
| topicPerms | topic=权限 | 每个 Topic 的权限 |
| groupPerms | group=权限 | 每个 Consumer Group 的权限 |
具体信息请参考 distribution/conf/plain_acl.yml 配置文件。
3. 支持访问控制的集群部署
如上所述，在 distribution/conf/plain_acl.yml 配置文件中定义权限属性后，您可以通过开启 aclEnable 开关变量来启用 RocketMQ 集群的 ACL 功能。以下是 Broker 上启用 ACL 功能的 properties 配置文件内容：
brokerClusterName=DefaultCluster
brokerName=broker-a
brokerId=0
deleteWhen=04
fileReservedTime=48
brokerRole=ASYNC_MASTER
flushDiskType=ASYNC_FLUSH
storePathRootDir=/data/rocketmq/rootdir-a-m
storePathCommitLog=/data/rocketmq/commitlog-a-m
autoCreateSubscriptionGroup=true
## if acl is open,the flag will be true
aclEnable=true
listenPort=10911
brokerIP1=XX.XX.XX.XX1
namesrvAddr=XX.XX.XX.XX:9876
4. 访问控制主流程
ACL 的主流程分为两个部分，主要包括权限解析和权限验证。
4.1 权限解析
Broker 解析客户端的 RequestCommand 请求，获取需要认证的属性字段，主要包括
- AccessKey: 类似于用户名，指代用户主体，与权限数据对应。
- Signature: 客户端使用 SecretKey 签名后得到的字符串，服务器随后使用 SecretKey 进行验证。
4.2 权限验证
Broker 侧的权限验证逻辑主要分为以下步骤
- 检查是否命中全局 IP 白名单；如果命中，则认为通过验证；否则，执行步骤 2。
- 检查是否命中用户 IP 白名单；如果命中，则认为通过验证；否则，执行步骤 3。
- 验证签名，如果验证失败，则抛出异常；如果通过，则执行步骤 4。
- 根据用户拥有的权限验证用户请求所需的权限；如果失败，则抛出异常。
用户所需权限的验证需要注意以下内容
- 特殊请求，如 UPDATE_AND_CREATE_TOPIC，只能由 admin 账户操作。
- 对于某个资源，如果存在显式配置的权限，则使用配置的权限；如果没有显式配置的权限，则使用默认权限。
5. 热加载修改后的访问控制定义
RocketMQ 访问控制的默认实现是基于 yml 配置文件的。用户可以在不重启 Broker 服务节点的情况下动态修改访问控制定义的属性。
6. 访问控制的使用限制
- 如果 ACL 与高可用部署（主从架构）一起启用，您需要在 Broker Master 节点的 distribution/conf/plain_acl.yml 配置文件中设置全局白名单信息，即将 Slave 节点的 IP 地址设置到 Master 节点的 plain_acl.yml 配置文件中的全局白名单中。
- 如果 ACL 与高可用部署（多副本 DLedger 架构）一起启用，由于节点故障时主节点将在 DLedger Group 中自动选择，因此您需要将 DLedger Group 中所有 Broker 节点的 plain_acl.yml 配置文件中的白名单设置为所有 Broker 节点的 IP 地址。
7. ACL mqadmin 配置管理命令
7.1 更新 ACL 配置文件中“account”属性的值
此命令示例如下：
$ sh mqadmin updateAclConfig -n 192.168.1.2:9876 -b 192.168.12.134:10911 -a RocketMQ -s 1234567809123 -t topicA=DENY,topicD=SUB -g groupD=DENY,groupB=SUB
说明：如果不存在，则在 ACL 配置 YAML 配置文件中创建；如果存在，则更新相应的“accounts”属性；如果指定了集群名称，则命令将在集群中的每个 Broker 节点上执行；否则，命令将在单个 Broker 节点上执行。
| 参数 | 值 | 定义 |
|---|---|---|
| n | 例:192.168.1.2:9876 | Namesrv 地址（必填） |
| c | 例:DefaultCluster | 指定集群名称（与 Broker 地址二选一） |
| b | 例:192.168.12.134:10911 | 指定 Broker 地址（与集群名称二选一） |
| a | 例:RocketMQ | Access Key 值（必填） |
| s | 例:1234567809123 | Secret Key 值（可选） |
| m | 例:true | 是否为管理员账户（可选） |
| w | 例:192.168.0.* | whiteRemoteAddress，用户 IP 白名单（可选） |
| i | 例:DENY;PUB;SUB;PUB|SUB | defaultTopicPerm，默认 Topic 权限（可选） |
| u | 例:DENY;PUB;SUB;PUB|SUB | defaultGroupPerm，默认 ConsumerGroup 权限（可选） |
| t | 例:topicA=DENY,topicD=SUB | topicPerms，每个 Topic 的权限（可选） |
| g | 例:groupD=DENY,groupB=SUB | groupPerms，每个 Consumer Group 的权限（可选） |
7.2 删除 ACL 配置文件中对应的“account”
此命令示例如下：
$ sh mqadmin deleteAccessConfig -n 192.168.1.2:9876 -c DefaultCluster -a RocketMQ
说明：如果指定了集群名称，则命令将在集群中的每个 Broker 节点上执行；否则，命令将在单个 Broker 节点上执行。参数“a”是 Access Key 的值，用于标识唯一的账户 ID，因此可以在命令参数中指定账户 ID。
| 参数 | 值 | 定义 |
|---|---|---|
| n | 例:192.168.1.2:9876 | namesrv 地址（必填） |
| c | 例:DefaultCluster | 指定集群名称（与 Broker 地址二选一） |
| b | 例:192.168.12.134:10911 | 指定 Broker 地址（与集群名称二选一） |
| a | 例:RocketMQ | Access Key 值（必填） |
7.3 更新 ACL 配置文件中的全局白名单
此命令示例如下：
sh mqadmin updateGlobalWhiteAddr -n 192.168.1.2:9876 -b 192.168.12.134:10911 -g 10.10.154.1,10.10.154.2
说明：如果指定了集群名称，则命令将在集群中的每个 Broker 节点上执行；否则，命令将在单个 Broker 节点上执行。参数“g”是全局 IP 白名单的值，用于更新 ACL 配置文件中的“globalWhiteRemoteAddresses”字段属性值。
| 参数 | 值 | 定义 |
|---|---|---|
| n | 例:192.168.1.2:9876 | namesrv 地址（必填） |
| c | 例:DefaultCluster | 指定集群名称（与 Broker 地址二选一） |
| b | 例:192.168.12.134:10911 | 指定 Broker 地址（与集群名称二选一） |
| g | 例:10.10.154.1,10.10.154.2 | 全局 IP 白名单（必填） |
7.4 查询集群 Broker 的 ACL 配置文件版本信息
此命令示例如下：
sh mqadmin clusterAclConfigVersion -n 192.168.1.2:9876 -c DefaultCluster
说明：如果指定了集群名称，则命令将在集群中的每个 Broker 节点上执行；否则，命令将在单个 Broker 节点上执行。
| 参数 | 值 | 定义 |
|---|---|---|
| n | 例:192.168.1.2:9876 | namesrv 地址（必填） |
| c | 例:DefaultCluster | 指定集群名称（与 Broker 地址二选一） |
| b | 例:192.168.12.134:10911 | 指定 Broker 地址（与集群名称二选一） |
7.5 查询集群 Broker 的 ACL 配置文件的全部内容
此命令示例如下：
sh mqadmin getAccessConfigSubCommand -n 192.168.1.2:9876 -c DefaultCluster
说明：如果指定了集群名称，则命令将在集群中的每个 Broker 节点上执行；否则，命令将在单个 Broker 节点上执行。
| 参数 | 值 | 定义 |
|---|---|---|
| n | 例:192.168.1.2:9876 | namesrv 地址（必填） |
| c | 例:DefaultCluster | 指定集群名称（与 Broker 地址二选一） |
| b | 例:192.168.12.134:10911 | 指定 Broker 地址（与集群名称二选一） |
特别注意：社区的当前版本已修复了在启用 Acl 认证后，Broker 在主从和 DLedger 模式下数据同步异常的问题。[4.5.1]具体 PR 链接为：https://github.com/apache/rocketmq/pull/1149