The broker works. That is a smaller claim than it sounds

EMQX 5.8.9 is installed, the Dashboard opens, and the tour in Part 2 built the mental model: a publisher sends a message on a topic, a subscriber asks for the topics it cares about, and the broker in the middle routes every message to whoever asked for it. All of that is still theory. You have not yet watched a single message travel through your own broker.

Fixing that takes one page of the Dashboard, because EMQX ships a test client inside it. And the moment you use it you will notice something the theory never mentioned: it connects with the Username and Password fields left blank, and it works.

That second point is not a scare story bolted onto a tutorial. Anyone who can reach your 1883 or your 8083 can publish to, and read, your entire topic space. The Woow add-on documentation lists “set up MQTT authentication after your first login” as required, not optional — which is why the first message and the first password belong in the same sitting rather than in two parts a week apart.

Diagnose → WebSocket Client, and the three menu items that are not there

There are several ways to talk to an MQTT broker. EMQX itself points at the desktop client MQTTX, the command-line MQTTX CLI and the browser build MQTTX Web. All three have to be installed, or at least remembered, somewhere outside EMQX. The fourth option does not: the WebSocket Client built into the Dashboard. It speaks MQTT over WebSocket, connects on port 8083 by default, and does all three actions — connect, subscribe and publish — right there in the page. For a first test tool that is the right trade.

You find it under Diagnose in the left menu. That menu holds five entries, and this is the part worth knowing before you go looking: three of them only exist in the paid EMQX Enterprise edition. On Open Source 5.8.9 you have two.

Hunting an Open Source interface for a menu item that was only ever in Enterprise is a rite of passage nobody enjoys. The table above is there to save you that particular afternoon.

What the page gives you

The WebSocket Client covers three stages — connect, subscribe, publish — and keeps two lists underneath: Published, what you sent, and Received, what came back. Click + to open several WebSocket connections at once, each one independent of the others. That is how you simulate two devices: one connection subscribing, another publishing.

One behavior surprises everyone exactly once. Refreshing this page clears every connection and all the sent and received data. It is a quick test tool, not a place that keeps history.

Four moves, and a message that comes back to you

The trick that makes this test so cheap is that you are going to be both ends at once. One connection subscribes to a filter, the same connection publishes to a topic that filter covers, and the broker routes the message back across to you. If the row appears in Received, every link in the chain worked.

1. Step 1

   Open the WebSocket client

   Log in to the EMQX Dashboard. If you changed the username and password after installing, in Part 1, use your own. In the left menu click Diagnose → WebSocket Client.

2. Step 2

   Make the first connection

   In the Connection block, leave Host as localhost and Port as 8083. Leave Username and Password empty — no authentication is set up yet, and that is exactly the state we are about to examine. Click Connect. When the status turns to Connected, you are through.

   Host: localhost

   Port: 8083

   If you have the Dashboard open from another device rather than from the machine itself, localhost means that other device and will not connect. Put your Home Assistant host address in the Host field instead.

3. Step 3

   Subscribe, then publish

   In the Subscription block set Topic to testtopic/# and click Subscribe. Then in the Publish block set Topic to testtopic/1, put {"msg":"Hello"} in Payload, start with QoS 0, and click Publish. The same message shows up in the Received area below, because you are the subscriber as well.

   Subscription topic: testtopic/#

   Publish topic: testtopic/1

   Payload: {"msg":"Hello"}
4. Step 4

   Verify QoS

   Change the Publish QoS to 1, send another message, and watch it reach Received just the same. Then try 2. Nothing dramatic happens on screen — and that is worth seeing for yourself before the next section explains what the three levels actually promise.

flowchart LR
  S["Subscription block:
subscribe to testtopic/#"] --> B
  A["Publish block:
publish to testtopic/1"] --> B["EMQX asks: does any live
subscription filter match
the topic testtopic/1?"]
  B --> D["Received list, in the very
same tab, because you are
the subscriber as well"]

There is one rule about that pair of topics that catches nearly everybody, and it is worth internalizing before you invent your own names. The Topic in the Publish block cannot carry the + or # wildcards. Only a Subscription topic may use them. A publish names one exact topic; a subscription describes a set.

flowchart TD
  A["The topic string you are
about to type"] --> B{"Does it contain
a + or a # ?"}
  B -->|"no"| C["Both blocks take it.
testtopic/1 is fine
on either side"]
  B -->|"yes"| D{"Which block are
you typing into?"}
  D -->|"Subscription"| E["Accepted. testtopic/# is
a filter, and it matches
testtopic/1"]
  D -->|"Publish"| F["Refused. A publish topic
names one exact topic"]

Three delivery guarantees, and none of them is “better”

QoS — Quality of Service — is the MQTT mechanism that controls how strongly the delivery of a single message is guaranteed. EMQX supports all three levels at both ends, and in the WebSocket client you pick one for the subscription and one for the publish.

Read that middle column again, because the shorthand people repeat — “higher is more reliable” — loses the part that actually bites. QoS 1 does not mean “more likely to arrive”; it means arrival is guaranteed and a duplicate is possible. If the thing on the other end opens a garage door, a duplicate is not a lesser problem than a loss.

The cheapest way to get a feel for it is the loop you already built: publish to a topic you subscribe to yourself. Because the publisher and the subscriber are the same end, the broker still routes the message across, and the Received rows let you confirm with your own eyes whether the same message comes back after a QoS change, and whether it arrives twice.

Retained is a separate switch

While you are in the Publish block, tick Retain and send one more message. The broker now remembers that message as the last one on that topic, and a new subscriber receives it immediately on subscribing instead of waiting for the next publish. Open a second connection with +, subscribe to testtopic/#, and it arrives before you have done anything else.

sequenceDiagram
  participant A as Connection A
  participant E as EMQX
  participant B as Connection B
  A->>E: publish testtopic/1, Retain ticked
  E->>E: store it as the retained message
  B->>E: subscribe to testtopic/#35;
  E->>B: hand over the retained message at once
  A->>E: publish testtopic/1 again, Retain ticked
  E->>B: deliver it as an ordinary message

Password-Based, with the built-in database

Everything so far worked with the Username and Password fields empty. Now we close that. Expand Access Control in the Dashboard's left menu and you get three items: Authentication, Authorization and Banned Clients, the blocklist. This part is the first of those. The second is Part 4.

EMQX keeps the two firmly apart, and the distinction is the single most useful thing in this section. Authentication answers “who are you?” — confirmed by a username and password, a client ID, a JWT or a similar mechanism. Authorization answers “what publishes and subscribes may this identity make?”

What you are choosing between

Creating an authenticator usually takes four steps: choose a Mechanism, choose a Backend that stores or fetches the data, fill in the connection details, and create it. The mechanisms are Password-Based (username and password), JWT (a token) and MQTT 5.0's SCRAM, a stronger, mutual check. The backends are the EMQX built-in database, an external database — MySQL, PostgreSQL, MongoDB or Redis — and an HTTP Server. JWT needs no backend at all.

flowchart LR
  M["Step 1
Mechanism"] --> P["Password-Based"]
  M --> J["JWT
(no backend to pick)"]
  M --> SC["SCRAM (MQTT 5.0)"]
  P --> B["Step 2
Backend"]
  B --> B1["Built-in Database"]
  B --> B2["MySQL / PostgreSQL /
MongoDB / Redis"]
  B --> B3["HTTP Server"]

For a home add-on install the practical choice is Password-Based plus Built-in Database. There is no second database to maintain, and adding a user directly in the Dashboard is enough to let Home Assistant and Zigbee2MQTT connect with a username and password. That is the route the steps below take.

1. Step 1

   Open the Authentication page

   In the Dashboard's left menu go to Access Control → Authentication, then click Create at the top right.

2. Step 2

   Create Password-Based plus the built-in database

   On the Create page pick Password-Based as the mechanism and Built-in Database as the backend. Set whether it matches on Username or ClientID, and which password hash to use, to suit your case. Then click Create. External databases and HTTP Server are left to the concept section below; you do not need them here.

3. Step 3

   Add a user

   Find the authenticator you just created in the Authenticator List, click User Management, and add a username and a password — for example ha_broker with a password of your own choosing. It is stored in the EMQX built-in database. Write the password down somewhere you will still have it when you point Home Assistant at the broker.

4. Step 4

   Prove it took effect, then put it back

   Go back to the WebSocket client from earlier in this part and connect with the credentials you just created — then try again with a deliberately wrong password and watch it be rejected. That rejection is the proof; a successful connection on its own does not tell you the authenticator is doing anything. If you also want to see what disabling does, turn this authenticator's Enable switch off in the Authenticator List, watch every client connect again, and turn it straight back on when the experiment is over. Delete any user you no longer need from User Management.

Two settings that will bite you later

The built-in database is the backend with the least to look after: usernames and passwords live in EMQX's own database and there is no separate data service to run. You can add and delete accounts by hand in User Management, or download the official template, fill it in, and use Import to create many at once. Two details on that page deserve more attention than they get.

The first is UserID Type: whether an account is identified by its username or by its client ID when it connects. It has to match the field your client actually sends: register an account by username, and a client that identifies itself only by client ID gives the check nothing to compare.

What the Enable switch really does

Each authenticator in the list has an Enable switch. The official documentation is explicit about what happens when you turn it off: after that, “all clients can connect.” It does not shut everyone out. It takes this identity check away.

flowchart TD
  A["A client sends CONNECT"] --> B{"Is an authenticator there,
with Enable switched on?"}
  B -->|"no authenticator, or Enable off"| C["Connected.
Every client is let in"]
  B -->|"yes"| D{"Do the credentials match
the built-in database?"}
  D -->|"no"| E["Rejected"]
  D -->|"yes"| F["Connected as that identity"]
  C --> G["Free to publish and subscribe
anywhere in the topic space,
until authorization is added"]
  F --> G

That bottom box is Part 4's job, and it is why finishing this part does not mean you are finished. Authentication is the half that has to come first, because there is nothing to write rules about until identities exist.

The three you should recognize, and probably not build today

The Create page offers more than the route you just took. You do not need any of it for a home install, but you should be able to recognize each one and know when it earns its place — otherwise you will either reach for the wrong one or spend an evening looking for one that is not in your edition.

JWT

JWT (JSON Web Token) is token-based authentication. The client puts a JWT token into the username or password field when it connects, and EMQX only has to check the signature and the claims in the Payload — which is why JWT needs no backend of its own. When you create it you choose Secret (verify with a shared key) or Public Key (verify with a public key), say whether the secret is Base64-encoded, and fill the claims you want checked into Payload.

If you use a JWKS Endpoint, EMQX periodically fetches a set of RSA or ECDSA public keys from the authorization server to verify the JWT, and you set the refresh interval in seconds. JWT fits the case where an existing identity service already issues the tokens and you only want EMQX to accept them too. For a plain self-hosted Home Assistant setup that is usually a bonus rather than a requirement: with no token-issuing service in the picture, a username and password is simpler.

HTTP Server

HTTP Server hands authentication to an external HTTP service that you provide yourself. EMQX sends every connection request to that URL and allows or denies it according to the response. You configure the request method (POST or GET), the request URL — which must include the http or https scheme — the headers, and the data to be checked in the body, usually username and password. It can sit on top of an account system you already have, but you have to maintain that service and make sure the response format is what EMQX expects. A broker whose authentication depends on a second service you wrote is a broker with a second thing that can fail at three in the morning.

LDAP

LDAP (Lightweight Directory Access Protocol) is the protocol for checking a user against a directory server. The important part first: in EMQX, LDAP is only available in the paid Enterprise edition, so you will not find it in your Open Source 5.8.9 Dashboard. Conceptually it borrows an existing LDAP directory as the source of accounts. If reusing an account directory you already run is the goal, your options under Open Source are the built-in database, or an HTTP Server fronting your existing identity service.

The failures that actually happen, in the order they happen

Where to go from here