Access control
1. Introduction to access control features
Access control (ACL) mainly provides RocketMQ with Topic resource level user access control. When using RocketMQ permission control, users can inject AccessKey and SecretKey signatures through RPCHook on the Client client; at the same time, set the corresponding permission control attributes (including Topic access permissions, IP whitelist and AccessKey and SecretKey signatures, etc.) in distribution/conf /plain_acl.yml configuration file. The Broker verifies the permissions owned by the AccessKey , but it throws an exception; the
ACL client can refer to the AclClient code in the org.apache.rocketmq.example.simple package .
2. Definition and attribute value of access control
2.1 Permission definition
The definition of RocketMQ's Topic resource access authority control is mainly shown in the following table, divided into the following four types
| Authority | meaning |
|---|---|
| DENY | Refuse |
| ANY | PUB or SUB permissions |
| PUB | Send permission |
| SUB | Subscription permission |
2.2 Key attributes of permission definition
| Field | Value | meaning |
|---|---|---|
| globalWhiteRemoteAddresses | *;192.168.*.*;192.168.0.1 | Global IP whitelist |
| accessKey | String | Access Key |
| secretKey | String | Secret Key |
| whiteRemoteAddress | *;192.168.*.*;192.168.0.1 | User IP whitelist |
| admin | true;false | Is an administrator account |
| defaultTopicPerm | DENY;PUB;SUB;PUB|SUB | Default topic permissions |
| defaultGroupPerm | DENY;PUB;SUB;PUB|SUB | Default ConsumerGroup permissions |
| topicPerms | topic=Permission | Permission of each topic |
| groupPerms | group=Permission | Permissions of each ConsumerGroup |
For details, please refer to the distribution/conf/plain_acl.yml configuration file
3. Cluster deployment with permission control
After defining the permission attributes in the distribution/conf/plain_acl.yml configuration file as described above, turn on the aclEnable switch variable to enable the ACL feature of the RocketMQ cluster. Here are the contents of the properties configuration file that enables ACL features on the Broker side:
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. The main process of permission control
The main process of ACL is divided into two parts, mainly including permission analysis and permission verification.
4.1 Permission analysis
The Broker side parses the client's RequestCommand request and obtains the attribute fields that require authentication.
Mainly include:
(1) AccessKey: similar to the user name, which refers to the user subject, and the authority data corresponds to it;
(2) Signature: the string obtained by the client based on the SecretKey signature, and the server uses the SecretKey for signature verification;
4.2 Permission verification
Broker's permission verification logic is mainly divided into the following steps:
(1) Check whether it hits the global IP whitelist; if it is, it is deemed to pass; otherwise, go to 2;
(2) Check whether it hits the user IP whitelist; If it is, then the verification is considered to be passed; otherwise, go to 3;
(3) Verify the signature, if the verification fails, and throw an exception; if the verification is passed, go to 4;
(4) Ask the user for the required permissions and user rights The permission you own is verified; if it fails, an exception is thrown; the
user needs to pay attention to the following content:
(1) Special requests such as UPDATE_AND_CREATE_TOPIC, etc., can only be operated by the admin account;
(2) For a certain For each resource, if there is an explicit configuration authority, the configured authority is adopted; if there is no explicit configuration authority, the default authority is adopted;
5. Permission control definition after hot loading modification
The default implementation of RocketMQ's permission control storage is based on the yml configuration file. Users can dynamically modify the attributes defined by access control without restarting the Broker service node.
6. Restrictions on access control
(1) If ACL and high-availability deployment (Master/Slave architecture) are enabled at the same time, you need to
set the global whitelist information in the distribution/conf/plain_acl.yml configuration file of the Broker Master node, which is to set the ip address of the Slave node To the global whitelist in the plain_acl.yml configuration file of the Master node.
(2) If ACL and high-availability deployment (multi-copy Dledger architecture) are enabled at the same time, since the Dledger Group will automatically select the master when a node is down, then it is necessary to
configure the plain_acl.yml of all Broker nodes in the Dledger Group group The whitelist of the file sets the ip addresses of all Broker nodes.
7. ACL mqadmin configuration management commands
7.1 Update the attribute value of "account" in the ACL configuration file
An example of this command is as follows:
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
Note: If it does not exist, it will be created in the ACL Config YAML configuration file; if it exists, the attribute value of the corresponding "accounts" will be updated;
if the cluster name is specified, the command will be executed on each broker node in the cluster; Otherwise, the command will be executed on a single broker node.
| parameter | Value | meaning |
|---|---|---|
| n | eg:192.168.1.2:9876 | namesrv address (required) |
| c | eg:DefaultCluster | Specify the cluster name (choose one from the broker address) |
| b | eg:192.168.12.134:10911 | Specify the broker address (choose one from the cluster name) |
| a | eg:RocketMQ | Access Key value (required) |
| s | eg:1234567809123 | Secret Key value (optional) |
| m | eg:true | Whether the administrator account (optional) |
| w | eg:192.168.0.* | whiteRemoteAddress, user IP whitelist (optional) |
| i | eg:DENY;PUB;SUB;PUB|SUB | defaultTopicPerm, default Topic permissions (optional) |
| u | eg:DENY;PUB;SUB;PUB|SUB | defaultGroupPerm, default ConsumerGroup permissions (optional) |
| t | eg:topicA=DENY,topicD=SUB | topicPerms, permissions of each topic (optional) |
| g | eg:groupD=DENY,groupB=SUB | groupPerms, permissions of each ConsumerGroup (optional) |
7.2 Delete the corresponding "account" in the ACL configuration file
An example of this command is as follows:
sh mqadmin deleteAccessConfig -n 192.168.1.2:9876 -c DefaultCluster -a RocketMQ
Note: If the cluster name is specified, the command will be executed on each broker node in the cluster; otherwise, the command will be executed on a single broker node.
Among them, the parameter "a" is the value of Access Key, which is used to identify the unique account id, so the account id can be specified in the parameter of the command.
| parameter | Value | meaning |
|---|---|---|
| n | eg:192.168.1.2:9876 | namesrv address (required) |
| c | eg:DefaultCluster | Specify the cluster name (choose one from the broker address) |
| b | eg:192.168.12.134:10911 | Specify the broker address (choose one from the cluster name) |
| a | eg:RocketMQ | Access Key value (required) |
7.3 Update the global whitelist in the ACL configuration file
An example of this command is as follows:
sh mqadmin updateGlobalWhiteAddr -n 192.168.1.2:9876 -b 192.168.12.134:10911 -g 10.10.154.1,10.10.154.2
Note: If the cluster name is specified, the command will be executed on each broker node in the cluster; otherwise, the command will be executed on a single broker node.
Among them, the parameter "g" is the value of the global IP white name, used to update the attribute value of the "globalWhiteRemoteAddresses" field in the ACL configuration file.
| parameter | Value | meaning |
|---|---|---|
| n | eg:192.168.1.2:9876 | namesrv address (required) |
| c | eg:DefaultCluster | Specify the cluster name (choose one from the broker address) |
| b | eg:192.168.12.134:10911 | Specify the broker address (choose one from the cluster name) |
| g | eg:10.10.154.1,10.10.154.2 | Global IP whitelist (required) |
7.4 Querying the version information of the cluster/Broker ACL configuration file
An example of this command is as follows:
sh mqadmin clusterAclConfigVersion -n 192.168.1.2:9876 -c DefaultCluster
Note: If the cluster name is specified, the command will be executed on each broker node in the cluster; otherwise, the command will be executed on a single broker node.
| parameter | Value | meaning |
|---|---|---|
| n | eg:192.168.1.2:9876 | namesrv address (required) |
| c | eg:DefaultCluster | Specify the cluster name (choose one from the broker address) |
| b | eg:192.168.12.134:10911 | Specify the broker address (choose one from the cluster name) |
7.5 查询集群/Broker的ACL配置文件全部内容
该命令的示例如下：
sh mqadmin getAccessConfigSubCommand -n 192.168.1.2:9876 -c DefaultCluster
说明：如果指定的是集群名称，则会在集群中各个broker节点执行该命令；否则会在单个broker节点执行该命令。
| 参数 | 取值 | 含义 |
|---|---|---|
| n | eg:192.168.1.2:9876 | namesrv地址(必填) |
| c | eg:DefaultCluster | 指定集群名称(与broker地址二选一) |
| b | eg:192.168.12.134:10911 | 指定broker地址(与集群名称二选一) |
特别注意开启Acl鉴权认证后导致Master/Slave和Dledger模式下Broker同步数据异常的问题，
在社区[4.5.1]版本中已经修复，具体的PR链接为：https://github.com/apache/rocketmq/pull/1149；