Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hivemq/hivemq-file-rbac-extension

HiveMQ extension for managing role-based authorization
https://github.com/hivemq/hivemq-file-rbac-extension

access-control extension file-based hivemq hivemq-extension mqtt permissions role-based-access-control security

Last synced: about 2 months ago
JSON representation

HiveMQ extension for managing role-based authorization

Awesome Lists containing this project

README 

        
:hivemq-link: http://www.hivemq.com

:hivemq-extension-docs-link: http://www.hivemq.com/docs/extensions/latest/

:hivemq-extension-docs-archetype-link: http://www.hivemq.com/docs/extensions/latest/#maven-archetype-chapter

:hivemq-blog-tools: http://www.hivemq.com/mqtt-toolbox

:maven-documentation-profile-link: http://maven.apache.org/guides/introduction/introduction-to-profiles.html

:hivemq-support: http://www.hivemq.com/support/

:hivemq-listener: https://www.hivemq.com/docs/hivemq/4.4/user-guide/listeners.html#tcp-listener

:hivemq-extension-download: https://www.hivemq.com/extension/file-rbac-extension/



= HiveMQ File Role based Access Control Extension



image:https://img.shields.io/badge/Extension_Type-Security-orange?style=for-the-badge[Extension Type]

image:https://img.shields.io/github/v/release/hivemq/hivemq-file-rbac-extension?style=for-the-badge[GitHub release (latest by date),link=https://github.com/hivemq/hivemq-file-rbac-extension/releases/latest]

image:https://img.shields.io/github/license/hivemq/hivemq-file-rbac-extension?style=for-the-badge&color=brightgreen[GitHub,link=LICENSE]

image:https://img.shields.io/github/actions/workflow/status/hivemq/hivemq-file-rbac-extension/check.yml?branch=master&style=for-the-badge[GitHub Workflow Status (branch),link=https://github.com/hivemq/hivemq-file-rbac-extension/actions/workflows/check.yml?query=branch%3Amaster]



== Purpose



The File Authentication and Authorization Extension implements Access Control based on a configuration file.



This extension implements the configuration for authentication and authorization rules via XML-file.

These mechanism are important to protect a MQTT deployment, and the data which is exchanged, from unwanted access.



The extension provides fine-grained control on a topic level to limit clients to specific topics and specific actions (publish or subscribe).

Substitution rules for clientId and username allow for dynamic roles to be applied to multiple clients, while still limiting each client to "their own" topics.



== Features



* Username and password based authentication for MQTT Clients

* Fine-grained access control on a topic-filter level

* Role based permission management

* Automatic Substitution of client identifier and username

* Runtime reload for Credentials and Roles

* Support for Hashed or Plain-text passwords

* Tooling to generate salted password hashes

* Option to define a set of listeners the extension is used for



== Installation



* Download the extension from the {hivemq-extension-download}[HiveMQ Marketplace^].

* Copy the content of the zip file to the `extensions` folder of your HiveMQ nodes.

* Modify the `extension-config.xml` and `credentials.xml` files for your needs.



== First Steps



Install the extension.

The users and roles from the example configuration files are now applied to all new MQTT connections.



== Next Steps



Setup your custom Users and Roles in the credentials configuration and configure the extension for your specific use case.



CAUTION: Because client identifier and usernames can be used for <> in the permissions, MQTT wildcard characters `#` and  `+` are prohibited for client identifier and usernames when this extension is used.

MQTT connections which include these characters are denied by this extension.



[#configuration]

== Configuration



This extension has two configuration files.

The <> file (`extension-config.xml`) that includes the general configuration for the extension itself.

And the <> file (`credentials.xml`) that includes the configuration of Users, Roles and Permissions.



The credentials configuration file is watched for changes and reloaded at runtime if necessary.

If the credentials configuration file has changed and contains a valid configuration, then the previous configuration is automatically archived to an archive folder `credentials-archive` inside the extension folder.

So that changes can be tracked and rolled-back if needed.

If the new credentials configuration is invalid the current configuration is maintained.



NOTE: The permissions for connected clients are not changed, only new connecting clients are affected.



[#credentials-config]

=== Credentials Configuration



The credentials configuration includes the following settings.



.Example credentials.xml

[source,xml]

----



    

        

            user1

            

            WFNQUVB0UkxjM04xa0hSR1BQNGhuOTJKVzdlbXA4bjk=:100:FY12nwpUEbBK9EKQ/Aw/rQKSoA7jXsC0HKELwU2mLCVU39bJVK0zf4NemuFeDOHPO4BW1nOjxi6NporkC6rUog==

            

                role1

            

        

        

            admin-user

            

            Vjc1a0lxQ3Nvb0ljNFVHNE9WRnM3RG1IZmdNUFcwVGY=:100:PL2FLqfpdhONG7qXjAMmdVn4wlMiXnypdXiFW09zqorFhKgoiixFQw2EVJJfE9Zn79q45V7Xpc6JeKLp0ntmYA==

            

                role1

                superuser

            

        

    

    

        

            role1

            

                

                    

                    data/${{clientid}}/#

                

                

                    

                    outgoing/${{clientid}}

                    PUBLISH

                    RETAINED

                

                

                    

                    incoming/${{username}}/actions

                    SUBSCRIBE

                

            

        

        

            superuser

            

                

                    

                    #

                

            

        

    



----



=== User Configuration



|===

|Configuration |Description

|`name` |Username that is presented by the client in the MQTT CONNECT packet.

|`password` |Password that is presented by the client in the MQTT CONNECT packet. Plain text or hashed passwords are supported.

|`roles` |List of IDs of a role which is defined in the same configuration file. The permissions of these roles are applied to the user.

|===



Hashed password strings for the credentials configuration can be generated by running the included password generator tool with the following command, from inside the extension folder.



.Example Usage

[source,bash]

----

java -jar hivemq-file-rbac-extension-4.5.3.jar -p mypassword

----



This tool can be used to generate salted password hashes for the extension credentials file (`credentials.xml`).

A custom salt can be passed with the `-s` parameter, by default a random salt is generated.

The amount of hashing iteration can be specified with the `-i` parameter.



.Example with hashed password

[source,xml]

----



    user1

    

    TUh5SWZlWmRNNzJQeXU0UkF2QmVKZXBBWFl6VU1Jc28=:gDR4bZ8kABBEL0WBflf09IMJahRlb1KGL2wJydlyWElfIu1F65SSU+RZZpjzy+vT4dDPJxiBSHM07wr56+bKsA==

    

        role1

    



----



.Example with plain text password

[source,xml]

----



    user1

    pass1

    

        role1

    



----



=== Role Configuration



|===

|Configuration |Description

|`id` |The ID for this role.

|`permissions` |A list of permissions which are applied for this role. Permissions are applied and checked by HiveMQ in the order they appear in the configuration file.

|===



=== Permission Configuration



|===

|Configuration |Default |Description

|`topic` |-|The topic on which this permission should apply. Can contain standard MQTT wildcards `#` and `+`. Also, special substitution with `${\{clientid}}` and `${\{username}}` is supported.

|`activity` |`ALL` |The activity which this client can perform on this topic. Can be `PUBLISH`, `SUBSCRIBE` or `ALL`.

|`qos` |`ALL` |The MQTT QoS which this client can publish/subscribe with on this topic. The value can be `ZERO`, `ONE`, `TWO`, `ZERO_ONE`, `ONE_TWO`, `ZERO_TWO` or `ALL`.

|`retain` |`ALL` |If a message published on this topic can/must be retained. Values are `NOT_RETAINED`, `RETAINED` or `ALL`. This setting is only relevant for PUBLISH messages.

|`shared-subscription` |`ALL` |If a subscription on this topic can/must be a shared subscription. Values are `SHARED`, `NOT_SHARED` or `ALL`. This setting is only relevant for SUBSCRIBE messages.

|`shared-group` |`#` |Limits the Shared Subscription group name for a subscription. Values are `#` to match all or a specific string value. This setting is only relevant for SUBSCRIBE messages that include a Shared Subscription.

|===



[#substitution]

=== Substitution



The special markers `${\{clientid}}` and `${\{username}}` in the topic filter for a permission are automatically replaced by the extension with the client identifier and username of the client for which authorization is performed.

This allows to configure a permission that applies to multiple clients, but always contains their specific client identifier or username in the topic.

Limiting each client to "their own" topics.



[#extensions-config]

=== Extension Configuration



The credentials configuration includes the following settings.



.Example extension-config.xml

[source,xml]

----



    

    60



    



    

    HASHED



    

    



----



|===

|Configuration |Default |Description

|`credentials-reload-interval` |`60` |Regular interval in seconds, in which the `credentials.xml` configuration file is checked for changes and reloaded.

|`listener-names` |`null` |List of names of listeners, this extension will be used for. See {hivemq-listener}[HiveMQ config details^].

|`password-type` |`HASHED` |How passwords are stored in the `credentials.xml` configuration file. Can either bei `PLAIN` for plain text passwords, or `HASHED` for a salted password hash.

|`next-extension-instead-of-fail` |`false` |The outcome in case the RBAC could not authenticate the client successfully.

If set to `false`, the client will get not authenticated (ConnAck packet with error code). If `true` then the RBAC extension

delegates the decision to the next extension with an authentication implemented, in case no other extension exists we

fail the authentication.

|===



NOTE: The `listener-names` feature requires the use of at least HiveMQ 4.1 / HiveMQ CE 2020.1



== Need Help?



If you encounter any problems, we are happy to help.

The best place to get in contact is our {hivemq-support}[support^].



== Contributing



If you want to contribute to HiveMQ File RBAC Extension, see the link:CONTRIBUTING.md[contribution guidelines].



== License



HiveMQ File RBAC Extension is licensed under the `APACHE LICENSE, VERSION 2.0`.

A copy of the license can be found link:LICENSE[here].