From c640d669c9c447c947d8b8324f7510310ab925be Mon Sep 17 00:00:00 2001 From: "Roger A. Light" Date: Fri, 5 Feb 2021 15:36:36 +0000 Subject: [PATCH] Add authentication methods doc. --- .../documentation/authentication-methods.md | 147 ++++++++++++++++++ www/pages/documentation/using-the-snap.md | 5 +- 2 files changed, 151 insertions(+), 1 deletion(-) create mode 100644 www/pages/documentation/authentication-methods.md diff --git a/www/pages/documentation/authentication-methods.md b/www/pages/documentation/authentication-methods.md new file mode 100644 index 00000000..f516956d --- /dev/null +++ b/www/pages/documentation/authentication-methods.md @@ -0,0 +1,147 @@ + + +It is important to configure authentication on your Mosquitto instance, so +unauthorised clients cannot connect. + +In Mosquitto 2.0 and up, you must choose your authentication options explicitly +before clients can connect. In earlier versions the default is to allow clients +to connect without authentication. + +There are three choices for authentication: password files, authentication +plugins, and unauthorised/anonymous access. It is possible to use a combination +of all three choices. + +It is possible to have different listeners use different authentication methods +by setting `per_listener_settings true` in your configuration file. + +As well as authentication you should also consider some form of access control +to determine what clients can access which topics. + +## Password files + +Password files are a simple mechanism of storing usernames and passwords in a +single file. They are good if you have a relatively small number of fairly +static users. + +If you make changes to the password file you must trigger the broker to reload +the file by sending a SIGHUP message: + +``` +kill -HUP +``` + +### Creating a password file + +To create a password file, use the `mosquitto_passwd` utility, use the line +below. You will be asked for the password. Note that `-c` means an existing +file will be overwritten: + +``` +mosquitto_passwd -c +``` + +To add more users to an existing password file, or to change the password for +an existing user, leave out the `-c` argument: + +``` +mosquitto_passwd +``` + +To remove a user from a password file: + +``` +mosquitto_passwd -D +``` + +You can also add/update a username and password in a single line, but be aware +that this means the password is visible on the command line and in any command +history: + +``` +mosquitto_passwd +``` + +### Configuring the broker + +To start using your password file you must add the `password_file` option to +your configuration file: + +``` +password_file +``` + +The password file must be able to be read by whatever user Mosquitto is running +as. On Linux/POSIX systems this will typically be the `mosquitto` user, and +`/etc/mosquitto/password_file` is a good place for the file itself. + +If you are using the `per_listener_settings true` option to have separate +security settings per listener, you must place the password file option *after* +the listener it is for: + +``` +listener 1883 +password_file /etc/mosquitto/password_file +``` + +## Authentication plugins + +If you want more control over authentication of your users than is offered by a +password file, then an authentication plugin may be suitable for you. The +features offered depend on which plugin you use. + +### Configuring the plugin + +Configuring a plugin varies depending on the version of Mosquitto plugin +interface the plugin was written for, either version 2.0 and up, or 1.6.x and +earlier. + +For 1.6.x and below, use the `auth_plugin` option. These plugins are also +supported by version 2.0: + +``` +listener 1883 +auth_plugin +``` + +Some plugins require extra configuration which will be described in their +documentation. + +For 2.0 and up, use the `plugin` option: + +``` +listener 1883 +plugin +``` + +### Available plugins + +* [Dynamic security](https://mosquitto.org/documentation/dynamic-security/), + for 2.0 and up only, provided by the Mosquitto project to give flexible + in-broker clients, groups, and roles that can be administered remotely. +* [mosquitto-go-auth](https://github.com/iegomez/mosquitto-go-auth), which + offers the use of a variety of backends to store user data, such as mysql, + jwt, or redis. + + +## Unauthenticated access + +To configure unauthenticated access, use the `allow_anonymous` option: + +``` +listener 1883 +allow_anonymous true +``` + +It is valid to allow anonmous and authenticated access on the same broker. In +particular the dynamic security plugin allows you to assign different rights to +anonymous users than to authenticated users, which may be useful for read-only +access to data for example. diff --git a/www/pages/documentation/using-the-snap.md b/www/pages/documentation/using-the-snap.md index d9926b20..41d6f3d4 100644 --- a/www/pages/documentation/using-the-snap.md +++ b/www/pages/documentation/using-the-snap.md @@ -14,7 +14,8 @@ graphical software installer, or with `snap install mosquitto`. After installing the Mosquitto snap, the Mosquitto broker will be running with the default configuration, which means it is listening for connections on port -1883. +1883 on the local computer only. If you want to allow connections from other +computers you must configure a listener and an [authentication method]. To test the broker, you can use the `mosquitto_pub` and `mosquitto_sub` command line utilities, which are also provided in the snap. `mosquitto_pub` allows you @@ -75,3 +76,5 @@ running as a snap. All other aspects of running Mosquitto are the same as with any other installation methods. + +[authentication method]:/documentation/authentication-methods