Version: 5.0

Access Control

1. Introduction to access control features

access control (ACL) mainly provides advanced access control functions at the Topic resource level for RocketMQ. When using RocketMQ access control, users can inject user name and password parameters into the client to achieve signature, and the server can implement permission management and verification of various resources through access control parameters.

info

ACL control will increase the complexity of deployment process and operation and maintenance management while enhancing cluster access control security. It is generally only recommended for use in scenarios where the network environment is not secure, business data is sensitive, and multiple departments and tenants are mixed. If the production cluster itself is a private cluster and is not accessed by external departments and tenants, it can be turned off.

2. Definition and attribute values of access control

2.1 Permission definition

The definition of access access control for RocketMQ Topic resources is mainly as shown in the following table, divided into the following four categories:

Permission	Definition
DENY	reject
ANY	PUB or SUB permission
PUB	send permission
SUB	subscribe permission

2.2 Key attributes of permission definitions

Field	Value	Definition
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	Whether it is an administrator account
defaultTopicPerm	DENY;PUB;SUB;PUB\|SUB	default Topic permission
defaultGroupPerm	DENY;PUB;SUB;PUB\|SUB	defalutl ConsumerGroup permission
topicPerms	topic=permission	Permissions for each Topic
groupPerms	group=permission	Permissions for each Consumer Group

Refer to the distribution/conf/plain_acl.yml configuration file for specific information.

3. Deployment of clusters supporting access control

After defining the permission attributes in the distribution/conf/plain_acl.yml configuration file as described above, you can turn on the ACL feature of the RocketMQ cluster by turning on the aclEnable switch variable. Here is the properties configuration file content for enabling the ACL feature on the Broker：

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. Main process of access control

The main process of ACL is divided into two parts, mainly including permission parsing and permission verification.

4.1 Permission parsing

The Broker parses the client's RequestCommand request and gets the attributes fields that need to be authenticated, mainly including:

AccessKey: Similar to a username, it refers to the user subject and corresponds to the permission data.
Signature: A string obtained by the client signing with the SecretKey, which the server then verifies with the SecretKey.

4.2 Permission verification

The permission verification logic on the Broker side is mainly divided into the following steps:

Check if it hits the global IP whitelist; if it is, it is considered to have passed the verification; otherwise, go to 2.
Check if it hits the user IP whitelist; if it is, it is considered to have passed the verification; otherwise, go to 3.
Verify the signature, if the verification fails, throw an exception; if it passes, go to 4.
Verify the permissions required by the user request against the permissions owned by the user; if it fails, throw an exception.

The verification of the required permissions for the user needs to pay attention to the following content:

Special requests such as UPDATE_AND_CREATE_TOPIC can only be operated by the admin account.
For a certain resource, if there is an explicit configuration permission, the configured permission is used; if there is no explicit configuration permission, the default permission is used.

5. Hot reload modified access control definitions

The default implementation of RocketMQ's access control storage is based on the yml configuration file. Users can dynamically modify the properties of the access control definition without restarting the Broker service node.