MQTT Client Credentials用于为系统中连接的客户端配置安全措施。
要在系统中创建新的客户端凭据，必须先以Admin用户身份认证。 该授权过程赋予您执行管理任务所需的权限和访问权。
以Admin用户身份认证后，您将有权创建和管理客户端凭据， 从而可为连接到系统的客户端实施可靠的安全措施。 该方法确保系统安全，仅有授权客户端可建立连接并与TBMQ交互。
认证
要对 broker 执行管理操作，必须先登录系统并获取 Access Token。 该 Access Token 用于对管理操作进行认证和授权。
要获取 Access Token，可执行以下命令：
1
2
3
4
5
6
curl --location --request POST 'http://localhost:8083/api/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
"username":"sysadmin@thingsboard.org",
"password":"sysadmin"
}'
请注意：若 broker 安装在远程服务器上，需将命令中的 “localhost” 替换为服务器公网 IP 或指定域名。 此外，请确保端口 8083 可从公网访问以建立连接。 同时，请将命令中的 “username” 和 “password” 替换为您环境中正确且有效的凭据。
授权成功后，响应中将包含一个名为 token 的字段。 后续所有 TBMQ 管理请求均需使用该 token。 为简化操作，您可以将 token 字段的值赋给名为 ACCESS_TOKEN 的环境变量， 或直接在本教程中涉及的请求里替换 $ACCESS_TOKEN 字符串。
1
export ACCESS_TOKEN=PLACE_YOUR_TOKEN_HERE
创建/更新MQTT Client Credentials
MQTT_BASIC 凭据示例：
1
2
3
4
5
6
7
8
curl --location --request POST 'http://localhost:8083/api/mqtt/client/credentials' \
--header "X-Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "testCreds",
"credentialsType":"MQTT_BASIC",
"credentialsValue":"{ \"clientId\": null, \"userName\": \"test_user\", \"password\": \"test_pass\", \"authRules\": { \"pubAuthRulePatterns\": [\"test\/.*\"], \"subAuthRulePatterns\": [\"my\/.*\"] } }"
}'
实施上述配置后，username为 test_user、password为 test_pass 的客户端将能成功登录系统。 但需注意，这些客户端将根据指定的主题访问权限受到限制。
使用这些凭据认证的客户端仅能发布到以 test/ 开头的主题。 此外，仅能订阅以 my/ 开头的主题。 该配置确保客户端访问被限制在特定主题模式内，从而维持受控且安全的环境。
SSL 凭据示例：
1
2
3
4
5
6
7
8
curl --location --request POST 'http://localhost:8083/api/mqtt/client/credentials' \
--header "X-Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "testSSLCreds",
"credentialsType":"X_509",
"credentialsValue":"{ \"certCnPattern\": \"Root Common Name\", \"certCnIsRegex\": false, \"authRulesMapping\": { \"test\": { \"pubAuthRulePatterns\": [\"test_ssl\/.*\"], \"subAuthRulePatterns\": [\"test_ssl\/.*\"] } } }"
}'
1
2
3
4
5
6
7
8
curl --location --request POST 'http://localhost:8083/api/mqtt/client/credentials' \
--header "X-Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "testSSLCredsWithPattern",
"credentialsType":"X_509",
"credentialsValue":"{ \"certCnPattern\": \".* Pattern Common Name .*\", \"certCnIsRegex\": true, \"authRulesMapping\": { \"test\": { \"pubAuthRulePatterns\": [\"test_ssl\/.*\"], \"subAuthRulePatterns\": [\"test_ssl\/.*\"] } } }"
}'
其中：
- certCnPattern - 证书链中应存在的common name匹配模式。
- certCnIsRegex - 控制common name (CN) 模式是否作为正则表达式 (regex) 进行匹配。
- authRulesMapping - 将客户端CN中提取的keyword映射到授权规则的规则（允许客户端仅发布和订阅特定主题）。
采用上述配置后，使用X.509 Certificate chain连接的客户端将根据特定条件被允许登录。 第一种情况中X.509 Certificate chain的证书CN应与 Root Common Name 精确匹配， 第二种情况应与 .* Pattern Common Name .* 匹配，且证书的CN应包含字符串 test。 使用这些凭据认证后，客户端将获得限于以 test_ssl/ 开头主题的发布和订阅权限。
获取所有MQTT Client Credentials
1
2
curl --location --request GET 'http://localhost:8083/api/mqtt/client/credentials?pageSize=100&page=0' \
--header "X-Authorization: Bearer $ACCESS_TOKEN"
注意，pageSize 参数为100、page 参数为0，因此上述请求将获取前100个MQTT客户端凭据。
删除MQTT Client Credentials
1
2
curl --location --request DELETE 'http://localhost:8083/api/mqtt/client/credentials/$CREDENTIALS_ID' \
--header "X-Authorization: Bearer $ACCESS_TOKEN"
将 $CREDENTIALS_ID 替换为要删除的MQTT客户端凭据的实际ID。