# hivemq-file-rbac-extension

**Repository Path**: henengorg/hivemq-file-rbac-extension

## Basic Information

- **Project Name**: hivemq-file-rbac-extension
- **Description**: hivemq身份验证插件
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 3
- **Created**: 2020-07-26
- **Last Updated**: 2023-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


== 基于HiveMQ File 角色的访问控制扩展

*扩展类型*:安全
*版本*:4.0.0
*许可证*:Apache许可证2.0

=== 设备连接方式

连接用户名:产品key
连接密码:产品秘钥
连接客户端id:产品秘钥

=== 目的

文件身份验证和授权扩展基于配置文件实现访问控制。

这个扩展通过xml文件实现身份验证和授权规则的配置。
这些机制对于保护MQTT部署和交换的数据不受不希望的访问非常重要。
该扩展在主题级别上提供细粒度控制，以将客户机限制为特定主题和特定操作(发布或订阅)。
该扩展在主题级别上提供细粒度控制，以将客户机限制为特定主题和特定操作(发布或订阅)。客户机Id和用户名的替代规则允许将动态角色应用于多个客户机，同时仍然将每个客户机限制为“它们自己的”主题。

=== 特性

* MQTT客户端基于用户名和密码的身份验证
* 在主题过滤器级别上进行细粒度的访问控制
* 基于角色的权限管理
* 自动替换客户标识符和用户名
* 运行时重新加载凭证和角色
* 支持Hashed或明文密码
* Tooling to generate salted password hashes

=== 安装

. 解压缩文件: `hivemq-file-rbac-extension-<version>-distribution.zip` 到目录: `<HIVEMQ_HOME>/extensions`
. 配置扩展 (`extension-config.xml`) 和凭证 (`credentials.xml`).
. 开始HiveMQ

=== 第一步

安装扩展。示例配置文件中的用户和角色现在应用于所有新的MQTT连接。

=== 第二部

在凭证配置中设置您的自定义用户和角色，并为您的特定用例配置扩展。

CAUTION: 因为客户端标识符和用户名可以用于<<substitution,权限>>中的替换，所以在使用此扩展时，MQTT通配符 `#` 和 `+` 禁止用于客户端标识符和用户名。包含这些字符的MQTT连接被此扩展拒绝。

[#configuration]
=== 配置

此扩展有两个配置文件。<<extensions-config,扩展配置>>文件(`extension-config.xml`)，包括扩展本身的一般配置。
以及<<credentials-config,凭证配置>>文件(`credentiars xml`)，其中包括用户、角色和权限的配置。

监视凭据配置文件的更改，并在必要时在运行时重新加载。如果凭证配置文件已更改并包含有效的配置，则先前的配置将自动存档到扩展文件夹中的存档文件夹(`credentiars -archive`)中。以便在需要时可以跟踪和回滚更改。
如果新的凭据配置无效，则维护当前配置。

NOTE: 已连接的客户端权限不会改变，只有新连接的客户端会受到影响。

[#credentials-config]
==== 凭证的配置

证书配置包括以下设置。

.样例 credentials.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<file-rbac>
    <users>
        <user>
            <name>user1</name>
            <!--- password hash for "pass1" -->
            <password>WFNQUVB0UkxjM04xa0hSR1BQNGhuOTJKVzdlbXA4bjk=:100:FY12nwpUEbBK9EKQ/Aw/rQKSoA7jXsC0HKELwU2mLCVU39bJVK0zf4NemuFeDOHPO4BW1nOjxi6NporkC6rUog==</password>
            <roles>
                <id>role1</id>
            </roles>
        </user>
        <user>
            <name>admin-user</name>
            <!-- password hash for "admin-password" -->
            <password>Vjc1a0lxQ3Nvb0ljNFVHNE9WRnM3RG1IZmdNUFcwVGY=:100:PL2FLqfpdhONG7qXjAMmdVn4wlMiXnypdXiFW09zqorFhKgoiixFQw2EVJJfE9Zn79q45V7Xpc6JeKLp0ntmYA==</password>
            <roles>
                <id>role1</id>
                <id>superuser</id>
            </roles>
        </user>
    </users>
    <roles>
        <role>
            <id>role1</id>
            <permissions>
                <permission>
                    <!-- PUBLISH and SUBSCRIBE to all topics below "data/<clientid>/" -->
                    <topic>data/${{clientid}}/#</topic>
                </permission>
                <permission>
                    <!-- PUBLISH to topic "outgoing/<clientid>", retained only-->
                    <topic>outgoing/${{clientid}}</topic>
                    <activity>PUBLISH</activity>
                    <retain>RETAINED</retain>
                </permission>
                <permission>
                    <!-- SUBSCRIBE to topic "incoming/<username>"-->
                    <topic>incoming/${{username}}/actions</topic>
                    <activity>SUBSCRIBE</activity>
                </permission>
            </permissions>
        </role>
        <role>
            <id>superuser</id>
            <permissions>
                <permission>
                    <!-- Allow everything -->
                    <topic>#</topic>
                </permission>
            </permissions>
        </role>
    </roles>
</file-rbac>
----

===== 用户配置


|===
| 配置 | 描述
|`name` | 客户机在MQTT连接包中提供的用户名。
|`password` | 客户机在MQTT连接包中提供的密码。支持纯文本或哈希密码。
|`roles` | 在同一配置文件中定义的角色的id列表。这些角色的权限应用于用户.
|===

可以在扩展文件夹中使用以下命令运行包含的密码生成器工具来生成凭据配置的散列密码字符串。

.示例使用
[source,bash]
----
java -jar hivemq-file-rbac-extension-4.0.0.jar -p mypassword
----

这个工具利用扩展配置文件(`extension-config.xml`)中的配置来生成与扩展设置相同的salted password。默认情况下，该工具在工作目录中搜索配置文件。

* 可以使用 `-c` 参数指定自定义位置。
* 可以通过 `-s` 参数传递自定义salt，默认情况下生成随机加盐哈希。
* 可以使用 `-i` 参数指定哈希迭代的数量。

.使用哈希密码的示例
[source,xml]
----
<user>
    <name>user1</name>
    <!--- password hash for "pass1" -->
    <password>TUh5SWZlWmRNNzJQeXU0UkF2QmVKZXBBWFl6VU1Jc28=:gDR4bZ8kABBEL0WBflf09IMJahRlb1KGL2wJydlyWElfIu1F65SSU+RZZpjzy+vT4dDPJxiBSHM07wr56+bKsA==</password>
    <roles>
        <id>role1</id>
    </roles>
</user>
----

.使用纯文本密码的示例
[source,xml]
----
<user>
    <name>user1</name>
    <password>pass1</password>
    <roles>
        <id>role1</id>
    </roles>
</user>
----

===== 角色配置

|===
|配置 | 描述
|`id` | 角色的ID。
|`permissions` | 用于此角色的权限列表。HiveMQ按照在配置文件中出现的顺序应用和检查权限。
|===

===== 权限许可配置

|===
|配置 | 默认 | 描述
|`topic` |-| 应应用此许可的主题。可以包含标准MQTT通配符 `#` 和 `+` 。还支持 `${{clientid}}` 和 `${{username}}` 的特殊替换。
|`activity` |`ALL` | 此客户端可以在此主题上执行的活动。可以是 `PUBLISH`、`PUBLISH`或 `ALL`.
|`qos` |`ALL` |此客户端可以就此主题发布/订阅的MQTT QoS。值可以是 `ZERO`, `ONE`, `TWO`, `ZERO_ONE`, `ONE_TWO`, `ZERO_TWO` 或 `ALL`.
|`retained` |`ALL` | 如果关于这个主题发布的消息可以/必须保留。值是 `NOT_RETAINED`、`RETAINED` 或 `RETAINED`。此设置仅与发布/PUBLISH 消息相关。
|`shared-subscription` |`ALL` | 如果此主题的订阅可以/必须是共享订阅。值是 `SHARED`, `NOT_SHARED` 或  `SHARED`, `NOT_SHARED`。此设置仅与订阅消息相关。
|`shared-group` |`#` | 限制订阅的共享订阅组名称。值是 `#` 来匹配所有或特定的字符串值。此设置仅适用于包含共享订阅的订阅消息。

|===

[#substitution]
===== 替换

 在主题过滤器中用于权限的特殊标记 `${{clientid}}` 和 `${{username}}`  被执行授权的客户端标识符和客户端用户名的扩展自动替换。这允许配置应用于多个客户机的权限，但始终在主题中包含它们的特定客户机标识符或用户名。将每个客户机限制为  "their own"  主题。

[#extensions-config]
==== 插件扩展配置

凭证配置包括以下设置.

.extension-config.xml 示例
[source,xml]
----
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<extension-configuration>

    <!-- Reload interval for credentials in seconds -->
    <credentials-reload-interval>60</credentials-reload-interval>

    <!-- If the credentials file is using HASHED or PLAIN passwords -->
    <password-type>HASHED</password-type>

</extension-configuration>

----


|===
|Configuration |Default |Description
|`credentials-reload-interval` |`60` |定期间隔秒，其中的 (`credentials.xml`) 的配置文件将检查更改并重新加载.
|`password-type` |`HASHED` | 密码存储在 `credentials.xml`  文件的方式。用  `PLAIN` 表示纯文本密码，也可以用  `HASHED`  表示加盐Hash密码.
|===

==== 需要帮助?

如果您遇到任何问题，我们很乐意帮助您。最好的 {hivemq-support}[联系^]方式是我们的网站。

= 许可

此插件
扩展在 `APACHE LICENSE, VERSION 2.0` 下获得许可。许可证的副本:link:LICENSE.txt[链接].