Device Connection Authentication

Updated on 2024-12-02 GMT+08:00

View PDF

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.

NOTE:

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

Parameter	Mandatory	Type	Description
ClientId	Yes	String	Explanation: 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. Value range: Up to 256 characters.
UserName	Yes	String	Explanation: The value is the device ID (device_id). Value range: Up to 256 characters.
Password	Yes	String	Explanation: The value is the value of the device secret encrypted by using the HMAC-SHA256 algorithm with the timestamp as the key. The device secret is returned by IoTDA upon successful device registration. Set this parameter only if the device authentication type is SECRET. Not required for X.509 certificate authentication (CERTIFICATES). Value range: Up to 256 characters.

Parameter

Mandatory

Type

Description

ClientId

Yes

String

Explanation:

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.

Value range:

Up to 256 characters.

UserName

Yes

String

Explanation:

The value is the device ID (device_id).

Value range:

Up to 256 characters.

Password

Yes

String

Explanation:

The value is the value of the device secret encrypted by using the HMAC-SHA256 algorithm with the timestamp as the key. The device secret is returned by IoTDA upon successful device registration.

Set this parameter only if the device authentication type is SECRET. Not required for X.509 certificate authentication (CERTIFICATES).

Value range:

Up to 256 characters.

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.