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":"[email protected]",
    "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\\/.*\"] } } }"
}'

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
`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/.

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.