MQTT Client Credentials

• Authentication
• Create/update MQTT Client Credentials
• Get all MQTT Client Credentials
• Delete MQTT Client Credentials

MQTT Client Credentials provide the means to configure security measures for connecting clients within the system.

To create new client credentials within the system, it is imperative to first authenticate as an Admin user. This authorization process grants you the necessary privileges and access rights to perform administrative tasks.

By authenticating as an Admin user, you will have the authority to create and manage client credentials, enabling you to enforce robust security measures for the clients connecting to the system. This approach ensures that the system remains secure and that only authorized clients can establish connections and interact with TBMQ.

Authentication

To carry out administrative operations with the broker, it is imperative to log into the system and obtain an Access Token. This Access Token is essential for authenticating and authorizing your administrative actions.

To acquire the Access Token, you can execute the following command:

1
2
3
4
5
6
curl --location --request POST 'http://localhost:8083/api/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username":"[email protected]",
    "password":"sysadmin"
}'

Please be aware that if the broker is installed on a remote server, you must substitute “localhost” in the provided command with either the public IP address of the server or a designated domain name. Moreover, ensure that port 8083 is accessible publicly to establish the necessary connection. Additionally, remember to replace the “username” and “password” values in the command with the appropriate and valid credentials specific to your setup.

Upon successful authorization, the response will include a valuable piece of information known as the token. It is crucial to utilize this token for all subsequent administrative requests to TBMQ. To streamline the process, you can either assign the value of the token field to an environment variable named ACCESS_TOKEN or directly replace occurrences of the $ACCESS_TOKEN string within the requests outlined in this tutorial.

1
export ACCESS_TOKEN=PLACE_YOUR_TOKEN_HERE

Create/update MQTT Client Credentials

MQTT_BASIC credentials example:

1
2
3
4
5
6
7
8
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\/.*\"] } }"
}'

By implementing the above configuration, clients with the username test_user and password test_pass will be able to successfully log in to the system. However, it’s important to note that these clients will have restricted privileges based on the specified topic access permissions.

Clients authenticated with these credentials will be limited to publishing messages solely to topics that start with test/. Additionally, they will be allowed to subscribe exclusively to topics that start with my/. This configuration ensures that the clients’ access is constrained to specific topic patterns, thereby maintaining a controlled and secure environment.

SSL credentials examples:

1
2
3
4
5
6
7
8
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":"SSL",
    "credentialsValue":"{ \"certCnPattern\": \"Root Common Name\", \"certCnIsRegex\": false, \"authRulesMapping\": { \"test\": { \"pubAuthRulePatterns\": [\"test_ssl\/.*\"], \"subAuthRulePatterns\": [\"test_ssl\/.*\"] } } }"
}'

1
2
3
4
5
6
7
8
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":"SSL",
    "credentialsValue":"{ \"certCnPattern\": \".* Pattern Common Name .*\", \"certCnIsRegex\": true, \"authRulesMapping\": { \"test\": { \"pubAuthRulePatterns\": [\"test_ssl\/.*\"], \"subAuthRulePatterns\": [\"test_ssl\/.*\"] } } }"
}'

Where:

• certCnPattern - the pattern for the common name that should be present in the certificate chain.
• certCnIsRegex - option to control whether the common name (CN) pattern is treated as a regular expression (regex) for matching.
• authRulesMapping - mapping rules to map extracted from the client’s CN keyword to the authorization rules (to allow clients to publish and subscribe only to certain topics).

By employing the above configurations, clients connecting with an X.509 Certificate chain will be permitted to log in based on specific criteria. The X.509 Certificate chain should have the certificate CN that matches exactly with the Root Common Name string in the first case, matches with .* Pattern Common Name .* in the second case, and the certificate’s CN should contain the string test. Once authenticated using these credentials, clients will gain access to publishing and subscribing privileges limited to topics that start with test_ssl/.

Get all MQTT Client Credentials

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

Note, pageSize parameter equal to 100 and page parameter equal to 0, so the above request will fetch first 100 MQTT client credentials.

Delete MQTT Client Credentials

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

Paste actual ID of the MQTT client credentials you want to delete instead of $CREDENTIALS_ID.