Device Connection Authentication

API Description

Devices can use this API to sent MQTT CONNECT messages to the platform for authentication. MQTT connections can be established between devices and the platform after successful authentication.

Parameters

Authentication is performed through an MQTT CONNECT message. The information contained in clientId must be intact. When receiving a CONNECT message, the platform checks the authentication type and password digest algorithm of the device.

When the timestamp is verified using the HMAC-SHA256 algorithm, the platform checks whether the message timestamp is consistent with the platform time and then checks whether the password is correct.
The timestamp must be contained in the CONNECT message even when the timestamp is not verified using the HMAC-SHA256 algorithm. In this case, the platform only checks the password.

If the authentication fails, the platform returns an error message and automatically disconnects the MQTT link.

Access the parameter generation tool and enter the device ID (DeviceId) and secret (DeviceSecret) generated after registration to generate the parameters (ClientId, Username, and Password) required for device connection authentication.

Parameter	Mandatory or Optional	Type	Description
clientId	Mandatory	String(256)	The value of this parameter consists of a device ID, device type, password signature type, and timestamp. They are separated by underscores (_). Device ID: A device ID uniquely identifies a device and is generated when the device is registered with IoTDA. The value usually consists of a device's product ID and node ID which are separated by an underscore (_). Device type: The value is fixed at 0, indicating a device ID. Password signature type: The length is 1 byte, and the value can be 0 or 1. 0: The timestamp is not verified using the HMAC-SHA256 algorithm. 1: The timestamp is verified using the HMAC-SHA256 algorithm. Timestamp: The UTC time when the device was connected to IoTDA. The format is YYYYMMDDHH. For example, if the UTC time is 2018/7/24 17:56:20, the timestamp is 2018072417.
userName	Mandatory	String(256)	Device ID.
password	Mandatory	String(256)	A password is the value of secret encrypted using the HMAC-SHA256 algorithm with the timestamp as the key. The device secret is returned by IoTDA upon successful device registration.

Parameter

Mandatory or Optional

Type

Description

clientId

Mandatory

String(256)

The value of this parameter consists of a device ID, device type, password signature type, and timestamp. They are separated by underscores (_).

Device ID: A device ID uniquely identifies a device and is generated when the device is registered with IoTDA. The value usually consists of a device's product ID and node ID which are separated by an underscore (_).
Device type: The value is fixed at 0, indicating a device ID.
Password signature type: The length is 1 byte, and the value can be 0 or 1.
- 0: The timestamp is not verified using the HMAC-SHA256 algorithm.
- 1: The timestamp is verified using the HMAC-SHA256 algorithm.
Timestamp: The UTC time when the device was connected to IoTDA. The format is YYYYMMDDHH. For example, if the UTC time is 2018/7/24 17:56:20, the timestamp is 2018072417.

userName

Mandatory

String(256)

Device ID.

password

Mandatory

String(256)

A password is the value of secret encrypted using the HMAC-SHA256 algorithm with the timestamp as the key.

The device secret is returned by IoTDA upon successful device registration.

Return Codes for Connection Setup Using Native MQTT

When a device attempts to establish a connection with the platform through native MQTT, one of the following codes may be returned:

Return Code	Description	Cause
0x00	Successful connection	The connection is successful.
0x01	Request rejected due to incorrect protocol version	The server does not support the MQTT version used by the client request.
0x02	Request rejected due to invalid client ID	The value of clientId is in an invalid format or the heartbeat interval does not meet the platform requirements.
0x03	Request rejected due to unavailable server	The platform service is unavailable.
0x04	Request rejected due to incorrect username or password	The username or password is incorrect.
0x05	Unauthorized request	The connection request of the client is not authorized.