In unique-certificate-per-device authentication mode, the application server applies for a unique access credential for each device first from the Message Queue for MQTT broker. The access credential includes the client ID, DeviceAccessKeyId, and DeviceAccessKeySecret. When a device establishes a connection to Message Queue for MQTT, it sends an authentication request to Message Queue for MQTT. The authentication request carries the UserName and Password parameters set based on the agreed rules by using information in the device access credential. Then, Message Queue for MQTT authenticates the device. If the authentication is successful, the device is activated and can transfer data with Message Queue for MQTT.

Terms

Term Description
Device access credential The globally unique credential used to access a device, which consists of the DeviceAccessKeyId and DeviceAccessKeySecret issued by the Message Queue for MQTT broker and the client ID. When the client establishes a connection to Message Queue for MQTT, the UserName and Password in the authentication request must be set by using the DeviceAccessKeyId and DeviceAccessKeySecret in the device access credential based on agreed rules.
Application server The server that you use to manage local accounts and apply for and manage device access credential services on behalf of clients.
Message Queue for MQTT broker The server Message Queue for MQTT uses for permission authentication and messaging. It processes requests related to device access credentials initiated by the application server and works as the broker for messaging between clients.

Calculation method

If unique-certificate-per-device authentication is used, in the connect message that the Message Queue for MQTT client sends for connecting to the Message Queue for MQTT broker, the UserName and Password parameters must be set based on the rules described in this topic. For more information, see Authentication overview. The following information describes the settings and calculation methods:

  • Username

    The UserName parameter consists of the authentication mode name, DeviceAccessKeyId, and Instance ID, which are separated with vertical bars (|). The mode name of unique-certificate-per-device authentication is DeviceCredential.

    For example, if a Message Queue for MQTT client whose client ID is GID_Test@@@0001 uses the instance ID mqtt-xxxxx and the DeviceAccessKeyId YYYYY, set the UserName parameter for connecting this client to DeviceCredential|YYYYY|mqtt-xxxxx.

    For more information about client IDs, see Terms.

  • Password

    The Password parameter indicates the client ID signature encoded in Base64. The following information describes the calculation method:

    For example, the Message Queue for MQTT client whose client ID is GID_Test@@@0001 uses the DeviceAccessKeySecret XXXXX.

    Calculate the signature of the string-to-sign GID_Test@@@0001 by using the HMAC SHA-1 algorithm to obtain a binary array. The DeviceAccessKeySecret XXXXX is used as the key for the HMAC calculation. Encode the binary array in Base64 to obtain the final string of the Password parameter.

    Function libraries are available for the implementation of the HMAC SHA-1 algorithm in different languages. You can search for one as required.

Authentication process

When you use the unique-certificate-per-device authentication mode, you must deploy your application server based on the following process. During initialization, Message Queue for MQTT clients must be able to interact with your application server to obtain and update device access credentials.
Figure 1. Authentication process
Unique-certificate-per-device authentication process

The authentication process consists of the following steps:

  1. The application server sends a request to the Message Queue for MQTT broker to apply for a device access credential for each Message Queue for MQTT client. The application server sends the request by calling the corresponding API operation.
  2. The Message Queue for MQTT broker authenticates the request and delivers the corresponding device access credential if the request is valid.
  3. The application server locally persists the returned device access credential. The locally cached device access credentials are mapped to clients. Caching of device access credentials brings the following benefits:
    • Device access credentials do not need to be updated unless they are leaked on the client side. The cached device access credentials are directly returned, which avoids overheads of API operation calls upon credential application.
    • If the Message Queue for MQTT client applies for a new device access credential but an error occurs to the Message Queue for MQTT broker, the application server returns the previously applied device access credential for local disaster recovery.
  4. The application server delivers the requested device access credential to the corresponding Message Queue for MQTT client.
  5. The Message Queue for MQTT client sets the device access credential as parameters based on agreed rules to connect to the Message Queue for MQTT broker. The Message Queue for MQTT client can send and receive messages after it is authenticated by the Message Queue for MQTT broker.

Client limits

  • You must set the UserName and Password parameters for connecting a Message Queue for MQTT client by using the DeviceAccessKeyId and DeviceAccessKeySecret in the device access credential based on agreed rules. The client uploads the parameters upon each connection.
  • The Message Queue for MQTT client must persistently store the device access credential returned by the application server to avoid applying for the same device access credential upon each connection. Otherwise, the application server may unexpectedly quit when it receives connection requests from many Message Queue for MQTT clients at the same time.

Application server limits

  • The application server must manage mappings between device access credentials and clients to prevent the same Message Queue for MQTT client from repeatedly calling the credential application operation.
  • The application server must implement local disaster recovery to prevent service blocking due to temporarily unavailable access to the Message Queue for MQTT broker.

Related API operations

You can call corresponding operations to implement authentication based on device access credentials. The application server is responsible for application and management of device access credentials, and interacts with the Message Queue for MQTT broker by calling operations over HTTPS.

Each operation requires authentication by using an AccessKey pair and a request signature. The API operations for creating, querying, deleting, and updating device access credentials are available. For more information about the API operations, see Unique-certificate-per-device authentication operations.