/docs/engineer/authentication-methods

MQTT Authentication: Password, JWT, and SCRAM

Compare None, Password, JWT, and SCRAM, configure the matching Mqttable fields, and verify an authenticated MQTT 5 connection.

Author:: Mqttable
Updated:: Aug 24, 2026

On this page7 sections

This guide follows the current Authentication Method control in Mqttable. Select MQTT 5.0 to use it; Mqttable hides the control for MQTT 3.1 and 3.1.1, and SCRAM is an MQTT 5 enhanced-authentication flow.

You are done when the Connection reaches Connected, Trace shows an accepted CONNACK, and a separate subscribe/publish test confirms that the authenticated identity also has the required Topic permissions.

Choose an authentication method

New clients default to Password. Use the method and exact credential format configured by the Broker operator. A method name alone is not enough: JWT claims and SCRAM hash variants must also match the listener policy.

None: Use only when the listener explicitly permits anonymous clients. Clear Username; choosing None disables the password controls and sends no password. Saved credentials are kept, but a non-empty Username can still be included in CONNECT.
Password: Use the username and password issued by the Broker operator. Mqttable sends them in CONNECT, so use TLS and prefer a saved SecretRef over repeatedly pasting a raw password.
JWT: Use when the Broker expects a JWT in the MQTT password field. The operator defines the signing algorithm, key, claims, audience, issuer, subject, and expiry policy.
SCRAM-SHA-256 or SCRAM-SHA-512: Prefer the exact stronger variant enabled by the Broker. Mqttable uses the username and password locally for the challenge-response exchange; the password is not placed in CONNECT.
SCRAM-SHA-1: Use only for compatibility with a Broker that explicitly requires this legacy hash. Do not substitute a different SCRAM variant: both peers must advertise the same method.

Configure None or Password

Save the Broker, then select New Client.
Keep MQTT 5.0 selected and choose the method required by the listener.
For None, clear Username and Password before connecting.
For Password, enter the issued Username and choose one password source:
- Raw password for a one-off test.
- Saved SecretRef for ongoing use. Create the password secret under Credentials first, then select its opaque reference here.
Use MQTTS, WSS, or QUIC when credentials cross an untrusted network. Authentication does not encrypt the transport.

Mqttable New Client form using MQTT 5 Password authentication with a saved password SecretRef — Password authentication sends the configured username and password in CONNECT; a Saved SecretRef keeps the raw value out of the form.
Choose MQTT 5.0 and Password when that matches the listener policy.
Use the Broker-issued username, not the local display name.
Saved SecretRef selects protected vault material without rendering its raw value.

Configure JWT

If the Broker operator gives you a complete token, paste it into Password or store it as a password SecretRef. Do not re-sign it.

Use JWT Tools only when you own the correct signing material and know the Broker's required claims:

Choose JWT as the Authentication Method.
Confirm whether Username is required separately by the listener.
Open JWT Tools.
Choose HS256 with the shared secret or RS256 with the PEM private key specified by the operator.
Set the exact claims required by policy. The initial username, iat, and exp rows are editable defaults, not proof that the Broker accepts them.
Select Generate & Fill, then inspect the token in Preview before connecting.

Mqttable New Client JWT Tools showing HS256 signing input and editable username, issued-at, and expiry claims — JWT Tools can sign HS256 or RS256 tokens locally; the Broker policy still determines the valid key, claims, and expiry.
The generated or supplied token is stored in the MQTT password field.
Select the operator-required signing algorithm and key material.
Review every claim and expiry before Generate & Fill.

The current source adds Open in JWT Debugger to the inline JWT Tools, preserving the generator and preview shown above. Inspect the current token’s signature and expiry, then return with the original draft or explicitly fill the password draft with the token. This does not save, connect, retrieve hidden saved credentials or pass signing keys to the debugger. Existing installers may not include this navigation yet; see Local tools for the workflow and temporary-data boundaries.

Never invent iss, aud, sub, or signing keys. A structurally valid JWT can still be rejected because its signature, claims, or clock window does not match Broker policy.

Configure SCRAM

Confirm that the listener supports MQTT 5 enhanced authentication and the exact method: SCRAM-SHA-1, SCRAM-SHA-256, or SCRAM-SHA-512.
Keep MQTT 5.0 selected, then choose that exact SCRAM variant.
Enter both Username and Password; Mqttable validates that neither is empty.
Prefer Saved SecretRef for the password when the Connection will be reused.
Connect. Mqttable places the SCRAM Authentication Method and challenge data in MQTT 5 authentication properties; it uses the password locally rather than sending it as the normal CONNECT password.

Mqttable New Client form using MQTT 5 SCRAM-SHA-256 and showing that a password is required — SCRAM requires MQTT 5, an exact method match, and both username and password; the inline error stops an incomplete setup.
MQTT 5.0 is required for Mqttable SCRAM authentication.
The selected SCRAM hash must match the Broker listener.
Username and password are both required before connecting.

Connect and verify authentication

Test Connection on the Broker form verifies the endpoint, transport, and TLS path only. It does not send the New Client authentication settings.

In the New Client form, select Connect.
Confirm that the client reaches Connected.
In Trace, find the outgoing CONNECT and incoming CONNACK.
Expect Connection Accepted. For SCRAM, also treat a completed enhanced-authentication exchange as part of the evidence.
Run an authorized subscribe/publish round trip. Connected proves the Broker accepted the client identity; it does not prove Topic authorization.

Troubleshoot by result

Form says JWT Token is required: Paste a complete token, select a populated SecretRef, or generate one with the correct key and claims. The form stops before connection.
Form says SCRAM credentials are required: Enter both Username and Password and keep MQTT 5.0 selected.
0x86 Bad User Name or Password: Recheck the client identity, secret or token, JWT signature and expiry, and whether the credential is enabled on this listener.
0x87 Not authorized: The Broker rejected the identity or its connection permission. If the client is already Connected and only publish or subscribe fails, inspect the Topic ACL instead.
0x8C Bad authentication method: Confirm MQTT 5 support and the exact SCRAM method configured on the listener. SHA-1, SHA-256, and SHA-512 are not interchangeable.
TLS handshake fails before CONNACK: Authentication has not been reached. Fix the endpoint, CA trust, server name, or mTLS setup with the TLS certificate guide.

Authentication boundaries and secret handling

Authentication is not TLS

Authentication proves a client identity to the Broker. TLS protects the network path and verifies the server; mTLS can additionally authenticate a client certificate. Passwords and JWTs still need a protected transport.

Authentication is not Topic authorization

An accepted CONNACK proves that the client may connect. SUBACK, PUBACK, or Broker policy may still reject a Topic operation. Verify both stages instead of replacing a valid password when the real failure is an ACL.

Keep raw secrets out of screenshots and shared logs

Use Saved SecretRef for reusable password or token material. Do not paste passwords, JWTs, HMAC secrets, or RSA private keys into tickets, chat, or screenshots. Rotate exposed material at the Broker, then replace the stored secret.

Continue with TLS certificates, Credentials, or the first MQTT message tutorial.