NEW
Docs Webinars Get Support
Kaa Documentation

MQTT Basic Credentials Authentication

Written by Andrew Pasika

Overview

In the Kaa IoT Platform, MQTT basic credentials provide a way to authenticate devices.
These credentials consist of a username and password, which are generated within the Kaa platform and assigned to individual devices.
During the MQTT connection handshake, the credentials are validated by the Kaa platform to confirm the device’s identity.

Configuring MQTT Basic Credentials

Go to “Device management” -> “Credentials”, and click the “Add basic credentials” button. Enter a username and password, then click “Create”. You will be presented with the generated username and password. Note that the entered username is suffixed with the @<tenantId> part. You must use this exact username to ensure the platform can resolve your tenant during the device authentication flow.

Generate credentials

After that, you should enable MQTT basic credentials authentication to require an MQTT username and password from all devices within your tenant. Without this step, the platform will still allow devices to communicate without presenting valid MQTT credentials. Once enabled, all currently active unauthenticated client sessions will be terminated.

If you want your other devices to continue communicating with the platform without presenting an MQTT username and password, you should disable MQTT basic credentials authentication after completing this guide.

Enable MQTT basic credentials authentication:

Enable MQTT basic credentials authentication

Connecting with MQTT Basic Credentials

Export your application version, endpoint token, MQTT username, and password as environment variables to use the shell examples below.

export APP_VERSION={app_version_name}
export ENDPOINT_TOKEN={endpoint_token}
export MQTT_USERNAME={username}
export MQTT_PASSWORD={password}

In this example, we will use the Kaa Cloud MQTT host: mqtt.cloud.kaaiot.com. Here we simultaneously publish temperature data and subscribe to the /error topic to see if any errors occur.

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/json/1/error -t kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/json/1 -u $MQTT_USERNAME -P $MQTT_PASSWORD -V 311 -m '{"temperature": 21}'

Go to the “Data logs” tab on the device page, and check for the arrived data.

Check arrived data

Also, return back to the “Credentials” page and check that credentials transitioned to the “Active” state.

Credentials state is active

Credentials can be in one of the following states:

  • Inactive is the initial state for newly provisioned credentials that has not been used to authenticate a client.
  • Active is the state credentials automatically move to after they were first used for client authentication. Credentials can be suspended or revoked from the active state.
  • Suspended state is for temporarily disabled credentials. Kaa will reject authentication requests with suspended credentials. Suspended credentials can be re-activated.
  • Revoked state is the terminal state for credentials that are no longer valid.

Credentials state machine

Connecting with Revoked MQTT Basic Credentials

Clicking on the context menu on the credentials row, you can suspend, revoke, or reset the password.

Let’s revoke the MQTT username and password and retry data publishing.

mosquitto_rr -h mqtt.cloud.kaaiot.com -e kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/json/1/error -t kp1/$APP_VERSION/dcx/$ENDPOINT_TOKEN/json/1 -u $MQTT_USERNAME -P $MQTT_PASSWORD -V 311 -m '{"temperature": 21}'

This time you will see an error.

Connection error: Unknown reason

Reverting Changes

As it was already stated, if you want your devices to continue communicating with the platform without presenting an MQTT username and password, you should disable MQTT basic credentials authentication.