Giter Club home page Giter Club logo

hivemq-file-rbac-extension's Introduction

HiveMQ File Role based Access Control Extension

Extension Type GitHub release (latest by date) GitHub GitHub Workflow Status (branch)

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 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 substitution 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

This extension has two configuration files. The extension configuration file (extension-config.xml) that includes the general configuration for the extension itself. And the credentials configuration 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 Configuration

The credentials configuration includes the following settings.

Example credentials.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>

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
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
<user>
    <name>user1</name>
    <!--- password hash for "pass1" -->
    <password>TUh5SWZlWmRNNzJQeXU0UkF2QmVKZXBBWFl6VU1Jc28=:gDR4bZ8kABBEL0WBflf09IMJahRlb1KGL2wJydlyWElfIu1F65SSU+RZZpjzy+vT4dDPJxiBSHM07wr56+bKsA==</password>
    <roles>
        <id>role1</id>
    </roles>
</user>
Example with plain text password
<user>
    <name>user1</name>
    <password>pass1</password>
    <roles>
        <id>role1</id>
    </roles>
</user>

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

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.

Extension Configuration

The credentials configuration includes the following settings.

Example extension-config.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>

    <!-- Optional list of names of listeners this extension is used for
    <listener-names>
        <listener-name>my-listener</listener-name>
        <listener-name>my-listener-2</listener-name>
    </listener-names> -->

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

    <!-- Use this option to toggle the behaviour in case authentication by this extension failed.
         false (default) -> client don't get authenticated
         true            -> instead of failing the authentication we delegate the decision to the next extension-->
    <!--next-extension-instead-of-fail>true</next-extension-instead-of-fail-->

</extension-configuration>

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 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 support.

Contributing

If you want to contribute to HiveMQ File RBAC Extension, see the contribution guidelines.

License

HiveMQ File RBAC Extension is licensed under the APACHE LICENSE, VERSION 2.0. A copy of the license can be found here.

hivemq-file-rbac-extension's People

Contributors

dependabot[bot] avatar donnerbart avatar fraschbi avatar lukasbrand avatar magierber avatar micwalter avatar sbaier1 avatar schaebo avatar sgtsilvio avatar yannickweber avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

hivemq-file-rbac-extension's Issues

PUBLISH Only Permission Not Working

Hello,
I am using this extension to limit topics and their sender and receiver.

i am using configuration like this:

<?xml version="1.0" ?>
<file-rbac>
<users>
<user>
    <name>test</name>		 
   <password>PASWORD-HASH</password>
    <roles>
        <id>role1</id>
    </roles>
</user>
</users>
<roles>
    <role>
        <id>role1</id>
    <permissions>
	<permission>
	    <topic>test</topic>
	    <activity>PUBLISH</activity>
	</permission>	
    </permissions>	
  </role>
</roles>
</file-rbac>

I can only publish message to test topic using test user, but when i subscribe, i also receive message. When activity is set to SUBSCRIBE, I cannot publish message, as it should be, but when its set to PUBLISH i also can subscribe.

password hash cannot be read from environment

Hi,

I try to pass a user's password hash in from an environment variable. Unfortunately this doesn't work - authentication fails. If I place the same hash inside the xml directly it works.

Is that supposed to work?

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<file-rbac>
    <users>
        <user>
            <name>client</name>
            <password>${ENV:PASSWORD_HASH}</password>
            <roles>
                <id>role</id>
            </roles>
        </user>
    </users>
...

Read the RBAC configuration from ConfigMap

Hi all,

I am trying to configure HiveMQ Broker with RBAC configuration via using configmap. I am deploying it with Kubernetes Operator to K8s cluster. However, configmap I created is set under the conf folder on hivemq-file-rbac-extension and it still continues to read default values. user1/pass1
I would like to be enlightened about point I miss.

I am adding the cm and values file values.

apiVersion: v1
kind: ConfigMap
metadata:
  name: hivemq-file-rbac-extension
  namespace: {{ .Release.Namespace }}
data:
  config.xml: |-
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <file-rbac>
        <users>
            <user>
                <name>test</name>
                <password>12345</password>
                <roles>
                    <id>role1</id>
                </roles>
            </user>
        </users>
        <roles>
            <role>
                <id>role1</id>
                <permissions>
                    <permission>
                        <topic>#</topic>
                    </permission>
                    <permission>
                        <topic>#</topic>
                        <activity>PUBLISH</activity>
                        <retain>RETAINED</retain>
                    </permission>
                    <permission>
                        <topic>#</topic>
                        <activity>SUBSCRIBE</activity>
                    </permission>
                </permissions>
            </role>
            <role>
                <id>superuser</id>
                <permissions>
                    <permission>
                        <topic>#</topic>
                    </permission>
                </permissions>
            </role>
        </roles>
    </file-rbac>

  extension-config.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>PLAIN</password-type>
    
    </extension-configuration>

  - name: hivemq-file-rbac-extension
    enabled: true
    # Defines if your custom extension supports hot-reload of its configuration, or if it needs to be restarted on configuration changes.
    supportsHotReload: true
    # The ConfigMap name that contains the extension configuration (will be mounted into the subfolder "conf" of the extension folder).
    configMapName: "hivemq-file-rbac-extension"
    # The Secret name that contains request headers for the custom extension download.
    requestHeaderSecretName: ""
    # The URI to download the custom extension (as .zip distribution).
    extensionUri: "https://www.hivemq.com/releases/extensions/hivemq-file-rbac-extension-4.5.3.zip"

And also I would like to let you know about error I get when I set credentials.xml instead of config.xml

When I check hivemq-platform object, it want to see config.xml for hivemq-file-rbac-extension CM I created.

image

And this shows how extension folder looks like

image

HiveMQ Version : 4.25.1
Opeartor: 1.1.0

Since I am not familiar with XML configuration, I would like to know what I am doing wrong.
If you need more details you want me to provide, please let me know.

Thank you in advance

RBAC and client certificate auth

Hello,

It seems it is not possible to configure HiveMQ to use both - RBAC and client certificate auth. If both are enabled then after client certificate is validated HiveMQ ask for username/password from client. That seems to be redundant.

Is there a configuration that for specific listerer I can disable RBAC file extension?

Thnx,
Goran

custom file path for credentials.xml and extension-config.xml

Use Case: updating credentials.xml with docker
It would be helpful to have the ability to set a custom file path (e.g. environment variable, having them in a sub folder would work as well) for the credentials.xml and extensions-config.xml for better docker compatibility.

Current Behavior: at the moment the two .xml files reside in the same folder as the .jar file itself, therefore using docker with an entire folder mapped to /opt/hivemq/extensions/hivemq-file-rbac-extension would overwrite the contents of the folder including the hivemq-file-rbac-extensionXXX.jar causing the extension not to be loaded.
Mapping the two files explicitly from the host inside the container /path/on/host/credentials.xml:/opt/hivemq/extensions/hivemq-file-rbac-extension/credentials.xml and /path/on/host/extension-config.xml:/opt/hivemq/extensions/hivemq-file-rbac-extension/extension-config.xml works fine until the credentials.xml is modified (e.g. adding or changing a role) due to this issue: moby/moby#15793 (comment)
The result is a changed file on the host and the file inside the container still being the previous version. Restarting the container will cause the new file to be loaded, however restarting hivemq for adding and removing credentials is highly inconvenient.

Desired Behavior: The ability to change the path where the config files are located to enable the possibility to use folder mounts. With folder mounts the config files changed on the host also change inside the container.

jdk version

What version of JDK is used in your project?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.