存取控制
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=permission | 每個 Topic 的權限 |
| groupPerms | group=permission | 每個 Consumer Group 的權限 |
具體請參考 distribution/conf/plain_acl.yml 組態檔。
3. 支援訪問控制的叢集部署
在 distribution/conf/plain_acl.yml 組態檔中定義好權限屬性後，如上所述，開啟 RocketMQ 叢集的 ACL 功能，可透過開啟 aclEnable 開關變數。以下是開啟 Broker 上 ACL 功能的屬性組態檔內容：
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 與高可用部署（Master/Slave 架構）一起啟用，則需要在 Broker Master 節點的 distribution/conf/plain_acl.yml 設定檔中設定全局白名單資訊，即在 Master 節點的 plain_acl.yml 設定檔中將 Slave 節點的 IP 地址設定為全局白名單。
- 如果 ACL 與高可用部署（多副本 Dledger 架構）一起啟用，由於節點掛掉時會在 Dledger Group 中自動選主，因此需要將 Dledger Group 中所有 Broker 節點的 IP 地址設定為所有 Broker 節點的 plain_acl.yml 設定檔中的白名單。
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 Config YAML 組態檔中建立；若已存在，則會更新對應的「accounts」屬性；若指定指定的叢集名稱，則指令會在叢集中的每個代理節點上執行；否則，指令會在單一代理節點上執行。
| 參數 | 值 | 定義 |
|---|---|---|
| n | 範例：192.168.1.2:9876 | Namesrv 地址（必填） |
| c | 範例：DefaultCluster | 指定叢集名稱（選擇與代理程式地址相符的叢集） |
| b | 範例：192.168.12.134:10911 | 指定代理程式地址（選擇與叢集名稱相符的代理程式） |
| a | 範例：RocketMQ | 存取金鑰值（必填） |
| s | 範例：1234567809123 | 秘密金鑰值（選填） |
| m | 範例：true | 是否為管理員帳戶（選填） |
| w | 範例：192.168.0.* | whiteRemoteAddress，使用者 IP 白名單（選填） |
| i | 範例：DENY;PUB;SUB;PUB|SUB | defaultTopicPerm，預設主題權限（選填） |
| u | 範例：DENY;PUB;SUB;PUB|SUB | defaultGroupPerm，預設消費者群組權限（選填） |
| t | 範例：topicA=DENY,topicD=SUB | topicPerms，每個主題的權限（選填） |
| g | 範例：groupD=DENY,groupB=SUB | groupPerms，每個消費者群組的權限（選填） |
7.2 刪除 ACL 組態檔中對應的「account」
此指令範例如下：
$ sh mqadmin deleteAccessConfig -n 192.168.1.2:9876 -c DefaultCluster -a RocketMQ
說明：若指定指定的叢集名稱，則指令會在叢集中的每個代理節點上執行；否則，指令會在單一代理節點上執行。參數「a」為存取金鑰的值，用於識別唯一的帳戶 ID，因此可以在指令參數中指定帳戶 ID。
| 參數 | 值 | 定義 |
|---|---|---|
| n | 範例：192.168.1.2:9876 | namesrv 地址（必填） |
| c | 範例：DefaultCluster | 指定叢集名稱（選擇與代理程式地址相符的叢集） |
| b | 範例：192.168.12.134:10911 | 指定代理程式地址（選擇與叢集名稱相符的代理程式） |
| a | 範例：RocketMQ | 存取金鑰值（必填） |
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
說明：若指定指定的叢集名稱，則指令會在叢集中的每個代理節點上執行；否則，指令會在單一代理節點上執行。參數「g」為全域 IP 白名單的值，用於更新 ACL 組態檔中的「globalWhiteRemoteAddresses」欄位屬性值。
| 參數 | 值 | 定義 |
|---|---|---|
| n | 範例：192.168.1.2:9876 | namesrv 地址（必填） |
| c | 範例：DefaultCluster | 指定叢集名稱（選擇與代理程式地址相符的叢集） |
| b | 範例：192.168.12.134:10911 | 指定代理程式地址（選擇與叢集名稱相符的代理程式） |
| g | 範例：10.10.154.1,10.10.154.2 | 全域 IP 白名單（必填） |
7.4 查詢叢集代理程式的 ACL 組態檔版本資訊
此指令範例如下：
sh mqadmin clusterAclConfigVersion -n 192.168.1.2:9876 -c DefaultCluster
說明：若指定指定的叢集名稱，則指令會在叢集中的每個代理節點上執行；否則，指令會在單一代理節點上執行。
| 參數 | 值 | 定義 |
|---|---|---|
| n | 範例：192.168.1.2:9876 | namesrv 地址（必填） |
| c | 範例：DefaultCluster | 指定叢集名稱（選擇與代理程式地址相符的叢集） |
| b | 範例：192.168.12.134:10911 | 指定代理程式地址（選擇與叢集名稱相符的代理程式） |
7.5 查詢叢集代理程式的 ACL 組態檔完整內容
此指令範例如下：
sh mqadmin getAccessConfigSubCommand -n 192.168.1.2:9876 -c DefaultCluster
說明：如果指定了集群名稱，則會在集群中的每個 Broker 節點上執行命令；否則，會在單一 Broker 節點上執行命令。
| 參數 | 值 | 定義 |
|---|---|---|
| n | 範例：192.168.1.2:9876 | namesrv 地址（必填） |
| c | 範例：DefaultCluster | 指定叢集名稱（選擇與代理程式地址相符的叢集） |
| b | 範例：192.168.12.134:10911 | 指定代理程式地址（選擇與叢集名稱相符的代理程式） |
特別注意：在啟用 Acl 認證後，Master/Slave 和 Dledger 模式下 Broker 異常資料同步的問題已在社區的 [4.5.1] 版本中修復。具體的 PR 連結為：https://github.com/apache/rocketmq/pull/1149