mosquitto/www/pages/documentation/dynamic-security.md

<!--
.. title: Dynamic Security Plugin
.. slug: dynamic-security
.. date: 2020-11-15 09:25:28 UTC
.. tags:
.. category:
.. link:
.. description:
.. type: text
-->


[TOC]

## Introduction

The Dynamic Security plugin is a Mosquitto plugin which provides role based
authentication and access control features that can be updated whilst the broker
is running, using a special topic based API.

It is supported since Mosquitto 2.0, and should be available in all
installations, but will not be activated by default.


## Concepts

This section describes the concepts of how the plugin operates. If you want to
find out how to use the plugin features, look in the [Installation] section below.

The plugin allows you to create three main objects, `clients`, `groups`, and `roles`.

This document will use the term `clients` to mean the clients defined in the
plugin, and `devices` or `users` to mean the MQTT clients that connect to the
broker.

---

### Clients

When you want a device or user to be able to connect and authenticate to the
broker, you create a client. Each client has the following attributes:

#### Username

The client username maps to the username provided in the CONNECT packet when a
device connects. The username is unique across the plugin, so attempting to
create a client with a duplicate username will result in an error. The username
acts as the primary key if you want to change anything about the client.

#### Password

The client password maps to the password provided in the CONNECT packet when a
device connects. The password may be unset when a client is created, this will
mean that devices will be unable to connect as the corresponding client.

The password can be updated at any point, but only by a client with the correct
access. Devices typically cannot update their own passwords.

#### Client ID

The client id maps to the client id provided in the CONNECT packet when a
device connects. This is an optional attribute.

If the client id is empty or not provided, then any device can connect with the
username for this client regardless of its client id. This means that multiple
devices could connect with the same credentials at the same time, but sharing
credentials between devices is not recommended.

If the client id is set, then a device can only connect as this client if the
triple of username, password, and client id all match those in the client.

#### Groups

A client can be a member of any number of groups.

#### Roles

A client can be assigned to any number of roles. A role gives the client access
to different topics.

#### Text name

This is an optional text field to give a human friendly name to this client.

#### Text description

This is an optional text field to give a human friendly description to this
client.

#### Disabled

A client can be set to be enabled/disabled at any point. Disabling a client
means that any devices currently connected using the credentials for that
client will be disconnected and unable to reconnect.

---

### Groups

Multiple clients can be placed in a group. Groups can have roles assigned to
them, so using groups is appropriate where you have a number of clients that
need to have the same access.

Groups have the following attributes:

#### Group name

The group name is the primary name for the group. It is used when modifying the
group in any way, such as adding a client or a role.

#### Roles

A group can be assigned to any number of roles. A role gives the group access
to different topics.

#### Text name

This is an optional text field to give a human friendly name to this group.

#### Text description

This is an optional text field to give a human friendly description to this
group.

---

### Roles

Roles contain multiple access control lists (ACLs), and can be assigned to clients and/or groups.

Roles have the following attributes:

#### Role name

The role name is the primary name for the role. It is used when modifying the
role in any way, such as adding an ACL.

#### Access Control Lists

ACLs are the feature which allows access to topics to be controlled. Checks are
made on different events as they happen: `publishClientSend`,
`publishClientReceive`, `subscribe`, and `unsubscribe`. The `publishClientSend`
event occurs when a device sends a PUBLISH message to the broker, i.e. "is the
device allowed to publish to this topic". The `publishClientReceive` event
occurs when a device is due to receive a PUBLISH message from the broker, i.e.
it has a valid subscription and a matching message has been published to the
broker. The `subscribe` event occurs in response to a device sending a
SUBSCRIBE message, and the `unsubscribe` event occurs in response to a device
sending an UNSUBSCRIBE packet.

The default behaviour of the different events can be set to allow or deny
access. The default behaviour applies if no matching ACL is found.

The default behaviour for the different events when the plugin has first been
configured is:

* `publishClientSend`: deny
* `publishClientReceive`: allow
* `subscribe`: deny
* `unsubscribe`: allow

There is some overlap between `publishClientReceive` and `subscribe`. In most
cases, using a `subscribe` ACL is sufficient to provide the control you need,
however by combining the two types it is possible to e.g. allow subscriptions
to a wildcard topic like `topic/#`, but deny access for device to receive
messages on a specific topic within that hierarchy like 'topic/secret'.

The different events have ACL types associated with them, and it is these ACLs
that you will add to your roles. Each ACL has a `topic`, a `priority`, and can
be set to `allow` or `deny`.

The `publishClientSend` and `publishClientReceive` ACL types map directly to
the events of the same name. The topic can contain wildcards, so allowing send
access to `topic/#` will allow devices to publish to all topics in the
`topic/#` hierarchy, including `topic`.

The `subscribe` and `unsubscribe` events have two ACL types each:
`subscribeLiteral`, `subscribePattern`, `unsubscribeLiteral`, and
`unsubscribePattern`.

The `*Literal` ACL types make a literal comparison between the topic filter
provided for the ACL and the topic filter provided in the SUBSCRIBE or
UNSUBSCRIBE message. This means that setting a `subscribeLiteral` ACL with
topic filter `#` to deny would prevent matching devices from subscribing the
the `#` topic filter only, but still allow them to subscribe to `topic/#`, for
example.

The `*Pattern` ACL types allow or deny access based on a wildcard comparison of
the ACL topic filter and the topic provided in the SUBSCRIBE or UNSUBSCRIBE
message. This means that setting a `subscribePattern` ACL with topic filter `#`
to deny would prevent matching devices from subscribing to any topic at all.

#### Text name

This is an optional text field to give a human friendly name to this role.

#### Text description

This is an optional text field to give a human friendly description to this
role.

---

### Priorities

If you are working with more than one role per client or group, or more than
one group per client, then it is crucial to understand how roles and ACLs are
applied.

The order in which checks are made is determined in part by the `priority` of
groups, roles and ACLs. Each client group has a priority, each client role and
group role has a priority, and each ACL within a role has a priority. If not
set explicitly, priorities will default to -1.

For each of the group, role, and ACL objects, checks are made in priority order
from the highest numerical value to the lowest numerical value. If two objects
of the same type have the same priority, then they will be checked in
lexographical order according to the username/groupname/rolename, but it is
advised to use unique priorities per object type.

When an event occurs that needs an ACL check, the ACLs for that ACL type are
checked in order until there is a matching ACL for the topic in question.

Within each role that is checked, the ACLs are checked in priority order.

The roles assigned to a client are checked first, in priority order.
Each client group is checked in priority order, with all of the roles in a
group being checked in priority order before the next group is checked.

As an example, let us assume we have the following client, groups, and roles:

Client: `sensor`
Groups: `temperature` (priority 2), `humidity` (priority 1)
Roles: `hallway`

Group: `temperature`
Roles: `input` (priority 5), `output` (priority 1)

Group: `humidity`
Roles: `humidity`

Role: `hallway`
ACLs: `Z` (priority 3), `A` (priority 1)

Role: `input`
ACLs: `Z` (priority 3), `A` (priority 3)

Role: `output`
ACLs: `Z` (priority 3), `A` (priority 1)

Role: `humidity`
ACLs: `Z` (priority 3), `A` (priority 1)

We are also assuming we are only looking at single ACL type.

If our client `sensor` triggers an ACL check, the ACLs will be checked in this
order, and the first matching ACL will be used to allow/reject the event:

1. sensor/hallway Z
2. sensor/hallway A
3. temperature/input A (alphabetical sort)
4. temperature/input Z (alphabetical sort)
5. temperature/output Z
6. temperature/output A
7. humidity/humidity Z
8. humidity/humidity A

This is provided as an example that covers all combinations of roles, it is
recommended to use as simple a setup as possible for your situation.

### Anonymous access

All of the documentation so far assumes that you do not allow anonymous
unauthenticated access - meaning devices or users that connect without a
username.

You may wish to allow anonymous access, but still make use of the dynamic
security plugin, and this is supported through the automatic anonymous group.
If allowed, anything connecting without a username will be assigned to a group
that you define. By assigning roles to that group, you can control what
anonymous devices can access.

## Installation

To use the Dynamic Security plugin, it must be configured in the broker and an
initial plugin configuration must be generated.

To configure the broker, add the following to your configuration file.

Linux/BSD:
```
plugin path/to/mosquitto_dynamic_security.so
plugin_opt_config_file path/to/dynamic-security.json
```

Windows:
```
plugin path\to\mosquitto_dynamic_security.dll
plugin_opt_config_file path\to\dynamic-security.json
```

On Linux you would expect the plugin library to be installed to
`/usr/lib/x86_64-linux-gnu/mosquitto_dynamic_security.so` or a similar path,
but this will vary depending on the particular distribution and hardware in
use.

It is recommended to use `per_listener_settings false` with this plugin, so all
listeners use the same authentication and access control.

The `dynamic-security.json` file is where the plugin configuration will be
stored. This file will be updated each time you make client/group/role changes,
during normal operation the configuration stays in memory. To generate an
initial file, use the `mosquitto_ctrl` utility.

```
mosquitto_ctrl dynsec init path/to/dynamic-security.json admin-user
```

Choose your own `admin-user` username. You will be asked for a password for the
client. This user will be assigned the `admin` role, which has the following
access:

* publishClientSend: `$CONTROL/dynamic-security/#` - this allows the client to
  control the Dynamic security plugin.
* publishClientReceive: `$CONTROL/dynamic-security/#` - this allows the client
  to receive information from the plugin. This is not necessary in the default
  configuration, but is included in case the default behaviour for
  `publishClientReceive` is set to `deny`.
* subscribePattern: `$CONTROL/dynamic-security/#` - this allows the client to
  receive information from the plugin.
* publishClientReceive: `$SYS/#` - this allows the client to see the broker
  metrics.
* subscribePattern: `$SYS/#` - this allows the client to see the broker
  metrics.
* publishClientReceive: `#` - this allows the client to examine the messages
  being published by other clients.
* subscribePattern: `#` - this allows the client to examine the messages
  being published by other clients.
* unsubscribePattern: `#` - this allows the client to undo previous
  subscriptions. This is not necessary in the default configuration, but is
  included in case the default behaviour for `unsubscribe` is set to `deny`.

The admin user does not have access to publish to normal application topics in
the `#` hierarchy by default. You are strongly encouraged to keep the admin
user purely for administering the plugin, and create other clients for your
application.

## Usage

All control of the plugin after initial installation is through the MQTT topic
API at `$CONTROL/dynamic-security/v1`. This allows integrations to be built,
but isn't the best choice for people to use directly. The `mosquitto_ctrl`
command provided with Mosquitto implements support for the dynamic security
plugin API, as described below. Other options include the [Management Center
for Mosquitto](https://docs.cedalo.com/latest/) which is an open source web
based tool for controlling the plugin and other features. The Management Center
is not part of the Mosquitto project.

### Using mosquitto_ctrl with a running broker

The initial configuration is the only time that `mosquitto_ctrl` does not
connect to a broker to carry out the configuration. All other commands require
a connection to a broker, and hence a username, password, and whatever else is
required for that particular connection. It is strongly recommended that your
broker connection uses encryption so that your configuration, including new
passwords, is not transmitted in plain text.

The connection options must be given before the `dynsec` part of the command
line:
```
mosquitto_ctrl <connection options> dynsec <command> ...
```

For example:

```
mosquitto_ctrl -u admin -h localhost dynsec <command> ...
```

It is possible to provide the admin password on the command line using `-P
password`, but this is not recommended. If you do not provide a password,
mosquitto_ctrl will ask you to enter the password when it is needed.

### Using an options file

For convenience, mosquitto_ctrl can load an options file which contains a list
of options it should use. This means you can set the encryption options, host,
admin username and any other options once and not have to add them to the
command line every time.

mosquitto_ctrl will try to load a configuration file from a default location.
For Windows this is at `%USER_PROFILE%\mosquitto_ctrl`. For other systems,
it will try `$XDG_CONFIG_HOME/mosquitto_ctrl` or
`$HOME/.config/mosquitto_ctrl`.

You may override this behaviour by manually specifying an options file with
`-o <path to options file>`.

The options file should contain a list of options, one per line, exactly as
they would be provided on the command line. For example:

```
--cafile /path/to/my/CA.crt
--certfile /path/to/my/client.crt
--keyfile /path/to/my/client.key
-u admin
-h mosquitto.example.com

```

### mosquitto_ctrl options

* `-A address` : Bind the outgoing connection to a local ip address/hostname.
  Use this argument if you need to restrict network communication to a
  particular interface.
* `--cafile path-to-ca.crt` : Define the path to a file containing PEM encoded
  CA certificates that are trusted. Used to enable SSL communication.  See also
  `--capath`
* `--capath` : Define the path to a directory containing PEM encoded CA
  certificates that are trusted. Used to enable SSL communication. For
  `--capath` to work correctly, the certificate files must have ".crt" as the
  file ending and you must run `openssl rehash <path to capath>` each time you
  add/remove a certificate. See also `--cafile`.
* `--cert path-to-client.crt` : Define the path to a file containing a PEM
  encoded certificate for this client, if required by the server. See also
  `--key`.
* `--ciphers` : An openssl compatible list of TLS ciphers to support in the
  client. See ciphers(1) for more information.
* `-d` : Enable debug messages.
* `--help` : Display usage information.
* `-h hostname` : Specify the host to connect to. Defaults to localhost.
* `-i client-id` : The id to use for this client. If not given, a client id
  will be generated depending on the MQTT version being used. For v3.1.1/v3.1,
  the client generates a client id in the format mosq-XXXXXXXXXXXXXXXXXX, where
  the X are replaced with random alphanumeric characters.  For v5.0, the client
  sends a zero length client id, and the server will generate a client id for
  the client.
* `--insecure` : When using certificate based encryption, this option disables
  verification of the server hostname in the server certificate. This can be
  useful when testing initial server configurations but makes it possible for a
  malicious third party to impersonate your server through DNS spoofing, for
  example. Use this option in testing only. If you need to resort to using this
  option in a production environment, your setup is at fault and there is no
  point using encryption.
* `--key path-to-client.key` : Define the path to a file containing a PEM
  encoded private key for this client, if required by the server. See also
  `--cert`.
* `-L url` : Specify specify user, password, hostname, port and topic at once
  as a URL. The URL must be in the form:
  `mqtt(s)://[username[:password]@]host[:port]`. If the scheme is mqtt:// then
  the port defaults to 1883. If the scheme is mqtts:// then the port defaults
  to 8883.
* `--nodelay` : Disable Nagle's algorithm for the socket. This means that
  latency of sent messages is reduced, which is particularly noticable for
  small, reasonably infrequent messages. Using this option may result in more
  packets being sent than would normally be necessary.
* `-p port` : Connect to the port specified. If not given, the default of 1883
  for plain MQTT or 8883 for MQTT over TLS will be used.
* `-P password` : Provide a password to be used for authenticating with the
  broker. Using this argument without also specifying a username is invalid
  when using MQTT v3.1 or v3.1.1. See also the `-u` option.
* `--proxy proxy-url` : Specify a SOCKS5 proxy to connect through. "None" and
  "username" authentication types are supported. The socks-url must be of the
  form `socks5h://[username[:password]@]host[:port]`. The protocol prefix
  socks5h means that hostnames are resolved by the proxy. The symbols %25, %3A
  and %40 are URL decoded into %, : and @ respectively, if present in the
  username or password.  If username is not given, then no authentication is
  attempted. If the port is not given, then the default of 1080 is used.
* `--psk key` : Provide the hexadecimal (no leading 0x) pre-shared-key matching
  the one used on the broker to use TLS-PSK encryption support.
  `--psk-identity` must also be provided to enable TLS-PSK.
* `--psk-identity identify` : The client identity to use with TLS-PSK support.
  This may be used instead of a username if the broker is configured to do so.
* `-q qos` : Specify the quality of service to use for messages, from 0, 1 and
  2. Defaults to 1.
* `--quiet` :  If this argument is given, no runtime errors will be printed.
  This excludes any error messages given in case of invalid user input (e.g.
  using `-p` without a port).
* `--tls-version version` : Choose which TLS protocol version to use when
  communicating with the broker. Valid options are tlsv1.3, tlsv1.2 and
  tlsv1.1. The default value is tlsv1.2. Must match the protocol version used
  by the broker.
* `-u username` : Provide a username to be used for authenticating with the
  broker. See also the `-P` argument.
* `--unix path` : Connect to a broker through a local unix domain socket
  instead of a TCP socket. This is a replacement for `-h` and `-L`. For
  example: `mosquitto_ctrl --unix /tmp/mosquitto.sock ...`.
* `-V protocol-version` : Specify which version of the MQTT protocol should be
  used when connecting to the remote broker. Can be `5`, `311`, `31`, or the
  more verbose `mqttv5`, `mqttv311`, or `mqttv31`. Defaults to `311`.


## Configuring default access

The initial configuration sets the default ACL type behaviours to:

* `publishClientSend`: deny
* `publishClientReceive`: allow
* `subscribe`: deny
* `unsubscribe`: allow

If you wish to change these, use `mosquitto_ctrl`.

```
mosquitto_ctrl <options> dynsec setDefaultACLAccess publishClientSend deny
mosquitto_ctrl <options> dynsec setDefaultACLAccess publishClientReceive deny
mosquitto_ctrl <options> dynsec setDefaultACLAccess subscribe deny
mosquitto_ctrl <options> dynsec setDefaultACLAccess unsubscribe deny
```

You can examine the current default access with the `getDefaultACLAccess` command:

```
mosquitto_ctrl <options> dynsec getDefaultACLAccess unsubscribe
```

## Creating and modifying clients

To create a new client:

```
mosquitto_ctrl <options> dynsec createClient <username>
```

This creates a client which does not have a client id associated with it. You
will be asked for the password for the new client before you are asked for the
admin user password. Pay attention to the messages on the command line.

```
mosquitto_ctrl <options> dynsec createClient <username> -i <client id>
```
This creates a client which has a client id associated with it.


To delete a client (clients connected with these credentials will be
disconnected from the broker):

```
mosquitto_ctrl <options> dynsec deleteClient <username>
```

To disable a client (clients connected with these credentials will be
disconnected from the broker):

```
mosquitto_ctrl <options> dynsec disableClient <username>
```

To enable a client (clients will be able to use these credentials to log in
again):

```
mosquitto_ctrl <options> dynsec enableClient <username>
```

To set a client password:

```
mosquitto_ctrl <options> dynsec setClientPassword <username>
mosquitto_ctrl <options> dynsec setClientPassword <username> <password>
```

To add/remove a role to/from a client:

```
mosquitto_ctrl <options> dynsec addClientRole <username> <rolename> <priority>
mosquitto_ctrl <options> dynsec removeClientRole <username> <rolename>
```

To get information on a client:

```
mosquitto_ctrl <options> dynsec getClient <username>
```

To list all clients:

```
mosquitto_ctrl <options> dynsec listClients
```

The `modifyClient` command also exists in the topic API, but is not currently available in `mosquitto_ctrl`.


## Creating and modifying groups

To create a new group:

```
mosquitto_ctrl <options> dynsec createGroup <groupname>
```

To delete a group:

```
mosquitto_ctrl <options> dynsec deleteGroup <groupname>
```

To add/remove a client to/from a group:

```
mosquitto_ctrl <options> dynsec addGroupClient <groupname> <username> <priority>
mosquitto_ctrl <options> dynsec removeGroupClient <groupname> <username>
```

In this case the `priority` refers to the priority of the group within the
client's list of groups.

To add/remove a role to/from a group:

```
mosquitto_ctrl <options> dynsec addGroupRole <groupname> <rolename> <priority>
mosquitto_ctrl <options> dynsec removeGroupRole <groupname> <rolename>
```

To set/get the group that anonymous devices are assigned to:

```
mosquitto_ctrl <options> dynsec setAnonymousGroup <groupname>
mosquitto_ctrl <options> dynsec getAnonymousGroup
```

To get information on a group:

```
mosquitto_ctrl <options> dynsec getGroup <groupname>
```

To list all groups:

```
mosquitto_ctrl <options> dynsec listGroups
```

The `modifyGroup` command also exists in the topic API, but is not currently
available in `mosquitto_ctrl`.

## Creating and modifying roles

To create a new role:

```
mosquitto_ctrl <options> dynsec createRole <rolename>
```

To delete a role:

```
mosquitto_ctrl <options> dynsec deleteRole <rolename>
```

To add an ACL to a role:
```
mosquitto_ctrl <options> dynsec addRoleACL <rolename> <acltype> <topic filter> allow|deny <priority>
```
Where `acltype` is one of `publishClientSend`, `publishClientReceive`,
`subscribeLiteral`, `subscribePattern`, `unsubscribeLiteral`, and
`unsubscribePattern`.

For example:

```
mosquitto_ctrl <options> dynsec addRoleACL <rolename> publishClientSend client/topic allow 5
```

To remove an ACL from a role using the topic filter as the key:
```
mosquitto_ctrl <options> dynsec removeRoleACL <rolename> <acltype> <topic filter>
```
For example:

```
mosquitto_ctrl <options> dynsec removeRoleACL <rolename> publishClientSend client/topic
```

To get information on a role:

```
mosquitto_ctrl <options> dynsec getRole <rolename>
```

To list all roles:

```
mosquitto_ctrl <options> dynsec listRoles
```

The `modifyRole` command also exists in the topic API, but is not currently
available in `mosquitto_ctrl`.