MQTT Security Fundamentals: Advanced Authentication Mechanisms


In the last post we already explained the basics of authentication and that the MQTT protocol provides username and password for authentication in the CONNECT message. This post will introduce additional mechanisms to authenticate a client and how authentication can be implemented on the MQTT broker side.

Authentication with other information

As we learned in the last post, authentication is a mechanism to confirm the identity of a party. We have already seen how this can be achieved by using a username and password combination. Besides username and password, MQTT clients provide additional information which can be used for authentication.

Client Identifier

Every MQTT client has a unique client identifier This unique identifier is provided by the client in the MQTT CONNECT message. A client id can be up to 65535 characters, the formerly limit of 23 characters was voided by the MQTT 3.1.1 specification. It is a common practice to use 36 character long uuids or any other unique information available to the client like the MAC address of the network module or the serial number of the device itself. In the authentication process client ids are often used in addition to username and password. A common example to confirm if a client can access the MQTT broker is to validate username/password and the correct client id for that credential combination. While it’s not a good security practice, it’s also possible to ignore the username/password and just authenticate against the client identifier. For a closed system this kind of authentication may be enough.

X.509 Certificate

Another possible authentication source from the client is a X.509 client certificate, which will be presented to the broker during the TLS handshake (we will explain more about transport level security and how SSL/TLS works together with MQTT in a later post). Some brokers like HiveMQ allow to use the information in the certificate for application layer authentication after the TLS handshake already succeeded. This enables the broker to read all informations contained in the certificate and use it for authentication purposes as well. If you are in control of the provisioning of IoT devices, X509 client certificates may be a very good source for authenticating clients on the MQTT broker.

Implementing Authentication with HiveMQ

We have seen that there is various information available for the authentication of an MQTT client. Now it’s time to wire the MQTT broker and the authentication store, which can be a database, a webservice, a LDAP directory or a simple ACL (access control list) Let’s take a look how the authentication logic can be implemented at the HiveMQ MQTT broker. The HiveMQ broker has an open source plugin system, which allows you to hook into a variety of events on the broker. HiveMQ has different callback interfaces, which are very easy to implement in custom plugins. The plugin implementations are called by the broker at runtime. For authentication purposes, HiveMQ provides the OnAuthenticationCallback.

This callback implementation is enough to customize the authentication mechanism to your use case. The method callback has one parameter, which is an object of the type ClientCredentialsData, which inherits of the type ClientData. This contains all data, which HiveMQ has available from the connecting client. It allows you to check client id, username, password and the certificate. If the client presented valid information for authentication, this callback returns true. In order to decline authentication, there are two possibilities:

  • return false
  • throw an Exception

If the callback returns false, HiveMQ will see if there are any other plugins and requests authentication from them. If one of them is returning true, HiveMQ accepts the authentication of the client. An exception should be thrown if HiveMQ should not consider any other plugins and refuse the connection immediately. When using the Exception, it’s also possible to modify the CONNACK return code. We have a more extensive example using a dummy implementation of username/password authentication on GitHub.

Before the callback is picked up from HiveMQ, it needs to be added to the callback registry. This can be easily done in the main class of a plugin. The main class is required in each plugin and can be identified easily, because it is the only class that extends PluginEntryPoint. The callback is injected via dependency injection and added to the callback registry. Now the plugin can be used together with the HiveMQ broker.

There are ready-to use HiveMQ (open source) plugins available for authenticating clients in our plugin directory, like the File Authentication Plugin for ACLs.
If you need more information about how to develop, run and deploy a custom authentication plugin for the HiveMQ broker, please read the plugin developer guide.

This is also the end of the authentication part of the MQTT Security Fundamentals. In the next post we will have a look at topic level authorization with MQTT.

We hope you enjoyed part three of the MQTT Security Fundamentals, if you want to get notify as soon as we publish the next post, you can subscribe to our newsletter or RSS feed. You think we have missed some important information? Please tell us, we are always open to questions and suggestions.


  1. manunited says:

    thank you very much
    but “ClientCredentialsData” and “ClientData” Links are not valid.
    please correct it.
    best regards

    1. Hi there,

      Thank you for pointing this out.
      Fixed it.

      Best regards,
      Florian from The HiveMQ Team.

  2. NuB2Hive says:

    Question on certificate. When you say “it allows you to check client id, username, password and the certificate”, are you assuming the certificate information is being extracted from the TLS level by HiveMQ broker? The client somehow tells it to use that? Or perhaps the plug-in requiring it makes HiveMQ get it (assuming it was used for mutual TLS at transport?) . Thanks.

    1. Hi there,

      the getCertificate() method will return an Optional of the client certificate, if there is a client certificate was used.
      HiveMQ will add this information to the ClientData after the connection was established.
      When there was no client certificate used during the connection, this method will return Optonal.absent().
      Keep in mind that the checks you can do on the plugin at this point, have nothing to do with the TLS validation.
      I hope this answers your question.

      Kind regards,
      Florian from the HiveMQ Team.

  3. NuB2Hive says:

    It does Florian, thanks. Ravi

Leave a Reply

Your email address will not be published. Required fields are marked *