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

Installation

1. Unzip the file: hivemq-file-rbac-extension--distribution.zip to the directory: <HIVEMQ_HOME>/extensions
2. Configure the extension (extension-config.xml) and the credentials (credentials.xml).
3. Start HiveMQ

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 user names can be used for substitution in the permissions, MQTT wildcard characters # and + are prohibited for client identifier and user names 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

<?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:PL2FLqfpdhONG7
            qXjAMmdVn4wlMiXnypdXiFW09zqorFhKgoiixFQw2EVJJfE9Zn79q45V7Xpc6JeKLp0ntmYA==</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

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

1

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

Example with hashed password

1
2
3
4
5
6
7
8
9

<user>
    <name>user1</name>
    <!--- password hash for "pass1" -->
    <password>TUh5SWZlWmRNNzJQeXU0UkF2QmVKZXBBWFl6VU1Jc28=:gDR4bZ8kABBEL0WB
    flf09IMJahRlb1KGL2wJydlyWElfIu1F65SSU+RZZpjzy+vT4dDPJxiBSHM07wr56+bKsA==</password>
    <roles>
        <id>role1</id>
    </roles>
</user>

Example with plain text password

1
2
3
4
5
6
7

<user>
    <name>user1</name>
    <password>pass1</password>
    <roles>
        <id>role1</id>
    </roles>
</user>

Role configuration

Permission configuration

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

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

</extension-configuration>

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

Need help?

Back to marketplace