Skip to main content
Version: Mosquitto 3.1

HTTP Authentication

Premium

Pro Mosquitto HTTP Authentication

The HTTP Authentication plugin can be used to authenticate MQTT clients by querying an HTTP endpoint on a remote web server.

To use the plugin, a configuration file must be specified (see example configuration for an example of such file and config file format section for the overview of all possible configuration parameters)

Plugin Activation​

To enable the HTTP Auth plugin on the broker, add the following to the mosquitto.conf file:

plugin /usr/lib/cedalo_http_auth.so

The plugin requires additional end user configuration to work, as described below.

Configuration​

The HTTP server address, request method, content type, and request parameters must be specified.

The server request address is the URL that the plugin must connect to in order to request authentication results.

plugin_opt_request_address https://127.0.0.1:8080/mqtt/auth

The HTTP request method is one of post, get, and put, which correspond to the HTTP method to use. It is recommended to use post.

plugin_opt_request_method post

The HTTP content type determines the format of the request data that will be sent to the HTTP server when making a POST request. It can be either application/x-www-form-urlencoded to use the traditional HTTP form encoding, or application/json to use JSON encoding. Choose the option that makes sense for your authentication application.

plugin_opt_request_header_content_type application/x-www-form-urlencoded

The request parameters determine what MQTT client parameters are sent to the server for use in the authentication. This option should be a text string of key=parameter values separated by commas. You choose the key names to match what you require and put the appropriate % parameter substitution from the list below.

The available parameters are:

  • %u : username
  • %c : client id
  • %a : client IP address
  • %P : clear text password
  • %p : client port
  • %C : TLS client certificate common name
  • %d : TLS client certificate subject

Note that the TLS client certificate parameters are only available if the client is using client certificates and if require_certificates true is set in the mosquitto configuration.

The %r parameter for client access protocol is not available. Please get in touch if this is important, and clarify what it should mean for you.

plugin_opt_request_params cid=%c,username=%u,ip-address=%a

Full configuration example​

plugin /usr/lib/cedalo_http_auth.so
plugin_opt_request_address https://127.0.0.1:8080/mqtt/auth
plugin_opt_request_method post
plugin_opt_request_header_content_type application/x-www-form-urlencoded
plugin_opt_request_params clientid=%c,username=%u,password=%P,ip=%a,port=%p,cn=%C,subj=%d

The HTTP server​

The HTTP server must respond to requests appropriately to allow/deny authentication. If the server responds with an HTTP response status code of 200, then the client will be authenticated. Any other respose status codes will result in the client not being authenticated, but it is suggested that the code 401 should be used for this purpose. If the server sends a code of 200 and the body of the response is exactly ignore, then the client will not be authenticated.