MQTT client credentials management

MQTT client credentials define authentication and authorization rules for connecting clients. Creating or managing credentials requires an authenticated admin user.

All examples below use curl. Replace localhost:8083 with your server address if TBMQ is running remotely.

Authentication

Obtain an access token by logging in:

curl --location --request POST 'http://localhost:8083/api/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username":"sysadmin@thingsboard.org",
    "password":"sysadmin"
}'

The response contains a token field. Export it for use in subsequent requests:

export ACCESS_TOKEN=PLACE_YOUR_TOKEN_HERE

Create or update MQTT client credentials

Basic (username/password) credentials

curl --location --request POST 'http://localhost:8083/api/mqtt/client/credentials' \
--header "X-Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "testCreds",
    "credentialsType":"MQTT_BASIC",
    "credentialsValue":"{ \"clientId\": null, \"userName\": \"test_user\", \"password\": \"test_pass\", \"authRules\": { \"pubAuthRulePatterns\": [\"test\\/.*\"], \"subAuthRulePatterns\": [\"my\\/.*\"] } }"
}'

Clients authenticated with these credentials (test_user / test_pass) can publish only to topics starting with test/ and subscribe only to topics starting with my/.

X.509 certificate credentials

Match by exact Common Name:

curl --location --request POST 'http://localhost:8083/api/mqtt/client/credentials' \
--header "X-Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "testSSLCreds",
    "credentialsType":"X_509",
    "credentialsValue":"{ \"certCnPattern\": \"Root Common Name\", \"certCnIsRegex\": false, \"authRulesMapping\": { \"test\": { \"pubAuthRulePatterns\": [\"test_ssl\\/.*\"], \"subAuthRulePatterns\": [\"test_ssl\\/.*\"] } } }"
}'

Match by CN regex pattern:

curl --location --request POST 'http://localhost:8083/api/mqtt/client/credentials' \
--header "X-Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "testSSLCredsWithPattern",
    "credentialsType":"X_509",
    "credentialsValue":"{ \"certCnPattern\": \".* Pattern Common Name .*\", \"certCnIsRegex\": true, \"authRulesMapping\": { \"test\": { \"pubAuthRulePatterns\": [\"test_ssl\\/.*\"], \"subAuthRulePatterns\": [\"test_ssl\\/.*\"] } } }"
}'

Match by exact Common Name and restrict the client ID with a regex:

curl --location --request POST 'http://localhost:8083/api/mqtt/client/credentials' \
--header "X-Authorization: Bearer $ACCESS_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "testSSLCredsWithClientId",
    "credentialsType":"X_509",
    "credentialsValue":"{ \"certCnPattern\": \"Root Common Name\", \"certCnIsRegex\": false, \"clientIdPattern\": \"sensor-.*\", \"clientIdIsRegex\": true, \"authRulesMapping\": { \"test\": { \"pubAuthRulePatterns\": [\"devices\\/${clientId}\\/.*\"], \"subAuthRulePatterns\": [\"devices\\/${clientId}\\/.*\"] } } }"
}'

X.509 credential fields:

Field	Description
`certCnPattern`	Pattern to match against the certificate’s Common Name
`certCnIsRegex`	When `true`, treats `certCnPattern` as a regular expression
`clientIdPattern`	Optional. Client ID the connecting client must use; omit it to accept any client ID
`clientIdIsRegex`	When `true`, treats `clientIdPattern` as a regular expression that must match the whole client ID
`authRulesMapping`	Maps a CN keyword to publish/subscribe authorization rule patterns

Clients connecting with a certificate chain are authorized when the CN matches the pattern. The test key in authRulesMapping means the CN must contain the string test; matched clients can publish and subscribe to topics starting with test_ssl/. The last example also requires the client ID to match the clientIdPattern regex sensor-.*, and its rules use ${clientId} to limit each client to topics under devices/ followed by its own client ID.

Get all MQTT client credentials

curl --location --request GET 'http://localhost:8083/api/mqtt/client/credentials?pageSize=100&page=0' \
--header "X-Authorization: Bearer $ACCESS_TOKEN"

pageSize=100 and page=0 returns the first 100 credentials.

Delete MQTT client credentials

curl --location --request DELETE 'http://localhost:8083/api/mqtt/client/credentials/$CREDENTIALS_ID' \
--header "X-Authorization: Bearer $ACCESS_TOKEN"

Replace $CREDENTIALS_ID with the actual ID of the credentials to delete.

Was this helpful?