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.
Install the extension. The users and roles from the example configuration files are now applied to all new MQTT connections.
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.
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.
The credentials configuration includes the following settings:
Example credentials.xml
|
|
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
|
|
Example with hashed password
|
|
Example with plain text password
|
|
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 the appear in the configuration file. |
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. |
retained | 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. |
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.
The credentials configuration includes the following settings.
Example extension-config.xml
|
|
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. |
Note:
Thelistener-names
feature requires the use of at least HiveMQ 4.1 / HiveMQ CE 2020.1