Client credentials

TBMQ provides multiple options for managing MQTT client credentials via the Web UI or REST API.

TBMQ supports the following credential types for authenticating MQTT client connections:

• Basic — authentication based on combinations of client ID, username, and password.
  • Advantages: Quick to implement, widely supported, low network overhead.
  • Disadvantages: Limited security.
• X.509 Certificate Chain — advanced security using an X.509 certificate chain to verify client identity.
  • Advantages: Mutual authentication between client and broker; more granular access control based on certificate subject attributes.
  • Disadvantages: More complex to set up, requires more expertise, higher compute cost for encryption/decryption.
• SCRAM — Salted Challenge Response Authentication Mechanism; secure, password-based authentication using the MQTT 5.0 enhanced authentication feature.
  • Advantages: Higher security than basic auth — uses a challenge-response process with hashed credentials so the password is never sent in plain text.
  • Disadvantages: Additional computational resources required for salted hash generation and validation.

Before using any of these credential types, ensure the matching authentication provider is enabled — see Basic, X.509, and SCRAM. If the matching authentication provider is disabled, the Credentials table shows a warning next to the affected credentials (e.g., “Basic Auth is disabled”). For a complete security overview, see the Security guide.

1. Go to Authentication → Credentials and click the Add Client Credentials button (plus icon).

2. Fill in the Name field (does not need to be unique).

3. Select the Client Type:

   • Device — for clients that publish frequently but subscribe to few topics with low message rate (IoT devices).
   • Application — for clients that subscribe to high message rate topics and require offline persistence (e.g., ThingsBoard, AWS IoT Core).

   See Client types for details.

4. Select the Credentials Type and configure authentication and authorization settings.

Go to the Credentials page and click the Add Client Credentials button, represented by a "plus" icon. Fill in the Name, Credentials Type. Fill in the Authentication settings. Set Authorization rules.

Basic authentication is based on combinations of client ID, username, and/or password:

Authorization rule patterns control which topics clients can publish or subscribe to, using regular expression syntax:

• country/.* — allows clients to publish/subscribe only to topics starting with country/.
• .* (default) — allows any topic.
• Empty — forbids all topics.

To change the password for Basic credentials:

1. Go to Authentication → Credentials and click on the credentials row.
2. Click the Change password button (labeled Set password if the credentials have no password yet).
3. Enter the current password, set a new one, and confirm.

Go to the Credentials page, click on the corresponding row and click the Edit button. Click the Change password button. Input your current password and set a new one. Click the Change password button.

X.509 Certificate Chain is a mutual TLS authentication method using a chain of public-key certificates.

The behavior depends on the Use certificate CN regex parameter:

• Disabled (exact match) — the Certificate Common Name (CN) must exactly match the client’s or one of the parent’s certificate CN.
• Enabled (regex match) — the CN regex is matched against the client’s certificate CN or parent CAs. Provides flexibility for batch client verification.

TLS authentication with "Use certificate CN regex" disabled to match certificate common name by exact match. TLS authentication with "Use certificate CN regex" enabled to match certificate common name using a regex pattern.

Authorization rules control topics based on the Client certificate CN matcher regex combined with publish/subscribe rule patterns:

• If the client certificate has CN cn_example_1 — set the CN matcher regex to cn_example_1, example_1, or .*example.*.
• If Publish authorization rule patterns are set to pub_topic/one/.*, pub_topic/two/.* — the client can only publish to topics starting with pub_topic/one/ or pub_topic/two/.
• If Subscribe authorization rule patterns are set to .* (default) — the client can subscribe to any topic.
• If Publish/Subscribe authorization rules are empty — the client is forbidden from publishing/subscribing to any topic.

SCRAM (Salted Challenge Response Authentication Mechanism) is an enhanced MQTT 5 authentication method based on username and password. The password is salted and hashed before storage — never transmitted in plain text.

• Username — unique identifier for the client.
• Password — secret string; salted and hashed before storage.
• Secure Hash Algorithm (SHA) — the hash algorithm for the password: SHA-256 offers better performance, SHA-512 higher security.

Authorization rule patterns control which topics clients can publish or subscribe to, using regular expression syntax:

• country/.* — allows clients to publish/subscribe only to topics starting with country/.
• .* (default) — allows any topic.
• Empty — forbids all topics.

Basic credentials can also be created in bulk — click the Import Basic credentials button (upload icon) in the top right corner and provide a CSV file. See Bulk provisioning for the file format and workflow.

1. Delete single — click the Delete icon in the credentials row, or open the credentials and click Delete Client Credentials.
2. Delete multiple — select multiple credentials using checkboxes, then click the Delete icon in the top right corner.

Delete single. Click on the icon "Delete". Delete multiple. Click on the checkboxes and confirm action by clicking on the button "Delete" in the top right corner.

Check Connectivity auto-generates mosquitto_sub and mosquitto_pub commands using the broker’s host, port, and the selected client credentials. Available for Basic credentials only. The generated commands use the host and port from the connectivity settings — the Go to Connectivity settings button (gear icon) in the top right corner of the Credentials page opens them.

1. Click the Check connectivity button.
2. Select your operating system.
3. Install the required client tools using the command shown.
4. Copy and run the generated commands.

Click on the button "Check connectivity" of the Basic client credentials. Select your operating system, install required tools, and copy commands.

If the credentials include a password, replace $YOUR_PASSWORD with the actual password:

mosquitto_sub -d -q 1 -h localhost -p 1883 -t tbmq/demo/+ -i "tbmq_eJzCIh6r" -u "tbmq_un_VxUVPaF8" -P "$YOUR_PASSWORD" -v
mosquitto_pub -d -q 1 -h localhost -p 1883 -t tbmq/demo/topic -i "tbmq_eJzCIh6r" -u "tbmq_un_VxUVPaF8" -P "$YOUR_PASSWORD" -m 'Hello World'

If the client has configured publish/subscribe authorization rule patterns different from the default .*, replace $YOUR_TOPIC with a topic the client is permitted to use.