Skip to content

Advanced Authentication Mechanisms - MQTT Security Fundamentals

by HiveMQ Team
9 min read

In our blog Authentication with Username and Password, we explained the basics of authentication and how the MQTT protocol provides a username and password in the CONNECT message for authentication. This blog introduces more ways to authenticate a client and shows you how to implement authentication on the MQTT broker.

MQTT Authentication with Other Information

In the last blog, we learned that authentication confirms the identity of something or someone. We also saw how a username and password combination can be used for authentication. In addition to the username and password, MQTT clients provide other information that can be used for authentication:

Client Identifier

Every MQTT client has a unique client identifier. The client provides this unique ID to the broker in the MQTT CONNECT message. The client ID can have a maximum of 65535 characters (the MQTT 3.1.1 specification removed the previous limit of 23 characters). It’s common practice to use the 36 character Universal Unique Identifier (UUID) or other unique client information as the client ID. For example, the MAC address of the network module or the device serial number. In the authentication process, client IDs are often used in combination with the username and password. A common way to confirm if a client can access the MQTT broker is to validate the username/password and the client ID that is correct for that credential combination. It is also possible to ignore the username/password and just authenticate against the client ID; however, this method is not a good security practice. (For some closed systems, this type of authentication may be sufficient).

X.509 Certificate

Another possible authentication method is using the X.509 client certificate. The client presents this certificate to the broker during the TLS handshake (we explain more about transport level security and how SSL/TLS works with MQTT in a later post). After a successful TLS handshake, some brokers such as HiveMQ permit use of certificate information for application layer authentication. This enables the broker to read all of the information in the certificate and use it for authentication purposes as well. If you provision IoT devices, X509 client certificates can be a very good source for authenticating clients on the MQTT broker.

Implementing Authentication with HiveMQ MQTT Broker

We’ve seen that there are different types of information available for 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 access control list (ACL). Let’s take a look at how authentication logic can be implemented on the HiveMQ MQTT broker.

The HiveMQ broker has an open source plugin system that allows you to hook into different events on the broker. HiveMQ offers various callback interfaces that are very easy to implement in custom plugins. The broker calls the plugin implementations at runtime. HiveMQ provides the OnAuthenticationCallback interface for authentication.

public class AuthWithUsernamePasswordCallback implements OnAuthenticationCallback {
    public Boolean checkCredentials(ClientCredentialsData clientCredentialsData) throws AuthenticationException 

    // Custom Authentication Logic


This callback implementation is sufficient for customizing the authentication mechanism to your use case. The callback method has one parameter of type ClientCredentialsData. This parameter contains all data that HiveMQ obtained from the connecting client. You can use this data to verify the client ID, username, password, and the certificate of the client. If the client presents valid information for authentication, this callback returns the value true.

There are two ways to decline authentication:

  • Returning the value false

  • Throwing an Exception

If the callback returns the value false, HiveMQ checks for other installed plugins and requests authentication from them. If one of these plugins returns the value true, HiveMQ authenticates the client. To prevent HiveMQ from checking other plugins and refuse the connection immediately, an exception must be thrown. In case of an exception, it is also possible to modify the CONNACK return code. We have an extensive example using a dummy implementation of username/password authentication on GitHub.

Callbacks must be registered with HiveMQ by adding them to the callback registry. This can be done easily in the main class of a plugin. The main class is required for each plugin and needs to extend the interface PluginEntryPoint. The callback is injected via dependency injection and added to the callback registry. Once the plugin is on the registry, it can be used with the HiveMQ broker.

public class AuthenticationExampleMainClass extends PluginEntryPoint {

    private final AuthWithUsernamePasswordCallback authWithUsernamePasswordCallback;

    public AuthenticationExampleMainClass(final AuthWithUsernamePasswordCallback authWithUsernamePasswordCallbackCallback)
        this.authWithUsernamePasswordCallback = authWithUsernamePasswordCallbackCallback;

    public void postConstruct() {

        CallbackRegistry callbackRegistry = getCallbackRegistry();


You can find ready-to use, open-source, HiveMQ plugins for authenticating clients in our plugin directory. For example, the File RBAC Extension for ACLs. If you need more information about how to develop, run, and deploy a custom authentication plugin for the HiveMQ broker, see the plugin developer guide.

This brings us to the end of the authentication part of MQTT Security Fundamentals. In the next post, we dive into topic-level authorization with MQTT.

We hope you enjoyed part three of the MQTT Security Fundamentals series. If you want to stay updated or get notified of our new content, subscribe to our newsletter or RSS feed. Feel free to use the comments section to ask questions or to leave feedback.

HiveMQ Team

The HiveMQ team loves writing about MQTT, Sparkplug, Industrial IoT, protocols, how to deploy our platform, and more. We focus on industries ranging from energy, to transportation and logistics, to automotive manufacturing. Our experts are here to help, contact us with any questions.

Related content:

Stopping the Scam: Anomaly Detection and Fraud Prevention with MQTT

Learn how MQTT & HiveMQ platform help provide deeper insights into IoT/IIoT data, detect anomalies as they occur, & safeguard against fraudulent activities.


Securing MQTT Devices with OIDC Authentication, HiveMQ, and Microsoft Entra

A step-by-step guide to secure MQTT devices and your IoT ecosystem with OIDC authentication, HiveMQ control center, and Microsoft Entra.


Authenticating MQTT Devices with HiveMQ and Microsoft Entra

Looking to authenticating MQTT Devices? Explore how to use HiveMQ Enterprise Security Extension for MQTT client authentication using Microsoft Entra ID.


Understanding HiveMQ’s ISO/IEC 27001 Certification for Information Security Management

Explore why & how HiveMQ adopted ISO/IEC 27001 information security management standard to protect data, intellectual property, & consumer information.


Navigating Cybersecurity Concerns in Industrial IoT Deployments

Explore how authentication, encryption, hardware security, audits, & tailored security approaches can help secure your IIoT systems against Cybersecurity.


Securing HiveMQ Broker Deployments With Intermediate CA Certificates

Learn how to secure HiveMQ MQTT broker deployments by adopting a hierarchical approach, with Root CA delegating authority to Intermediate CAs.


Securing Data in IoT Deployments

Learn how to enhance the security of IoT deployments while using MQTT, the de facto protocol for IoT, and HiveMQ’s Enterprise Security Extension (ESE).


Reinforcing Security of OT Systems in IIoT with MQTT and HiveMQ

Explore potential attacks on an MQTT Broker, security challenges in OT for IIoT, and discover how MQTT and HiveMQ can effectively mitigate these threats.


Securing the Unified Namespace Architecture for IIoT

Learn how to address key security challenges associated with Unified Namespace (UNS) in IIoT environments with actionable strategies and best practices.


Step Up Your MQTT Security with JWT Authentication on HiveMQ Cloud Starter

Explore how JSON Web Token (JWT) feature in HiveMQ Cloud Starter helps bring advanced security measures to your MQTT projects. Learn more.


Enhance Your IoT Security with Client Certificate Authentication on HiveMQ Cloud Starter

Explore the security enhancement to HiveMQ Cloud Starter. The feature, Client Certificate Authentication, helps with IoT security. Learn more.


Configuring HiveMQ Control Center Authentication and Authorization with Microsoft Active Directory

Learn how to configure HiveMQ's Control Center to authenticate and authorize users through Microsoft Active Directory.


Ask Me Anything: MQTT Experts Answer Your Questions | July 2022 Edition

The July 2022 edition of AMA session answers your most pressing questions around MQTT, MQTT security, MQTT Sparkplug, MQTT on cloud platforms and IoT architecture.


IoT Security Issues and MQTT

A webinar discussing IoT security issues and how MQTT can actually mitigate security vulnerabilities in IoT and IIoT infrastructures.


HiveMQ is not affected by Log4Shell

Announcement about HiveMQ and the recent security vulnerability known as Log4Shell.


How to Setup, Run, and Scale a Secure MQTT Broker on Kubernetes

How HiveMQ can be deployed into any Kubernetes cluster - managed in the public cloud or hand-crafted in your on-premise environment.


Implementing the Five Pillars of IT Security for MQTT

Learn how the five pillars of IT security can be implemented to secure IoT applications using MQTT, and how to create a secure IoT system with MQTT and HiveMQ.


Setting up TLS for your cloud-based MQTT broker

Step by step guide on configuring HiveMQ to utilize mutual TLS encryption for device to server communication as well as inter server communication.


A Better Solution for IoT Security and MQTT

The new HiveMQ Enterprise Security Extension is built to meet security requirements of IoT business.


MQTT Security Fundamentals - Wrapping up the complete series

Get the entire list of MQTT Security Fundamentals in one go. Learn how to secure your IoT and IIoT applications.


Securing MQTT Systems - MQTT Security Fundamentals

MQTT Security Fundamentals: Learn how to secure MQTT deployments and harden the deployment to prevent cyberattacks.


MQTT Message Data Integrity - MQTT Security Fundamentals

Explore how to sign MQTT messages. Find out how digital signatures/MACs, and checksums for MQTT messages work and what problems they solve.


Payload Encryption - MQTT Security Fundamentals

Explore this MQTT Security Fundamentals blog discussing why and when MQTT payload encryptions should be used, how it works & what are the advantages.


OAuth 2.0 & MQTT - MQTT Security Fundamentals

MQTT Security Fundamentals: Learn the basic concepts of Oauth 2.0 and how it plays along with MQTT clients and brokers.


X509 Client Certificate Authentication - MQTT Security Fundamentals

Learn how to add an additional layer of security to MQTT with X509 client certificates and find out the challenges of using this approach


TLS/SSL - MQTT Security Fundamentals

MQTT Security Fundamentals: Learn about transport encryption with TLS/SSL while implementing MQTT.


Authorization - MQTT Security Fundamentals

Learn how authorization works in MQTT. Take your MQTT security to next level and safeguard the communication between your IoT devices.


HiveMQ MQTT Security Fundamentals

MQTT Security Fundamentals, a blog series by HiveMQ, offers all the necessary information you need to secure your MQTT, IoT and IIoT applications.


Authentication with Username and Password - MQTT Security Fundamentals

Learn how to authenticate and secure your MQTT client and broker communication at transport and application level using username and password.

HiveMQ logo
Review HiveMQ on G2