All Products
Search
Document Center

ApsaraMQ for MQTT:Overview of unique-certificate-per-device authentication

Last Updated:Oct 10, 2023

In unique-certificate-per-device authentication mode, an application server applies for a unique access credential for each device from the corresponding Message Queue for MQTT broker. The access credential of a device consists of the client ID, AccessKey ID, and AccessKey secret of the device. When a device establishes a connection to ApsaraMQ for MQTT, the device sends an authentication request to ApsaraMQ for MQTT. The authentication request contains the UserName and Password parameters that are configured by using the information in the access credential based on the predefined rules. After the ApsaraMQ for MQTT broker receives the authentication request, the broker authenticates the device. If the authentication is successful, the device is activated and can transfer data with ApsaraMQ for MQTT.

Terms

TermDescription
device access credentialThe globally unique credential that is issued by the Message Queue for MQTT broker to a Message Queue for MQTT client. A device access credential consists of the AccessKey ID, AccessKey secret, and client ID of the client. When the client establishes a connection to ApsaraMQ for MQTT, the UserName and Password parameters in the authentication request must be configured by using the AccessKey ID and AccessKey secret in the device access credential based on the predefined rules.
application serverThe server that you use to manage local accounts and apply for and manage device access credentials on behalf of clients.
Message Queue for MQTT brokerThe server that ApsaraMQ for MQTT uses for permission authentication and messaging. A Message Queue for MQTT broker processes device access credentials-related requests that are initiated by the application server and works as an intermediary for the messaging between clients.

Specify the UserName and Password parameters

This section describes the rules based on which you can specify the UserName and Password parameters in the connect message that a Message Queue for MQTT client sends to a Message Queue for MQTT broker to perform unique-certificate-per-device authentication. For more information, see Authentication overview.

  • Username

    A valid value of the UserName parameter consists of the authentication mode name, the AccessKey ID of the client, and the instance ID. The three parts are separated with vertical bars (). If you want to enable unique-certificate-per-device authentication, set the authentication mode to DeviceCredential.

    For example, the client ID of a Message Queue for MQTT client is GID_Test@@@0001. The corresponding instance ID is mqtt-xxxxx. The AccessKey ID of the client is YYYYY. In this case, set the UserName parameter to DeviceCredentialYYYYYmqtt-xxxxx.

    For more information about client IDs, see Terms.

  • Password

    The Password parameter specifies the signature of a client ID. The following example shows how to calculate the signature of a client ID:

    The client ID of a Message Queue for MQTT client is GID_Test@@@0001, and the AccessKey secret of the client is 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 AccessKey secret XXXXX is used as the key for the HMAC calculation. Encode the binary array in Base64 to obtain the final signature string for the Password parameter.

    Each programming language comes with a function library for the implementation of the HMAC SHA-1 algorithm. You can use the corresponding functions based on your business requirements.

Procedure

When you use the unique-certificate-per-device authentication mode, deploy your application server based on the following process. During initialization, make sure that your Message Queue for MQTT client can interact with your application server to obtain and update the device access credential.
Figure 1. Authentication processUnique-certificate-per-device authentication process

The unique-certificate-per-device authentication process is divided into the following steps:

  1. The application server sends an API request to the Message Queue for MQTT broker to apply for a device access credential for the Message Queue for MQTT client.
  2. The Message Queue for MQTT broker authenticates the request. If the broker determines that the request is valid, the broker issues the corresponding device access credential.
  3. The application server stores the returned device access credential in the local cache and maps the device access credential to the client. Caching of device access credentials provides the following benefits:
    • Device access credentials do not need to be updated unless they are leaked on the client. When the client reconnects to the broker, the application server can return a device access credential to the client directly from the cache. This eliminates the overhead of calling an API operation to apply for an access credential.
    • If the Message Queue for MQTT client applies for a new device access credential and an error occurs on the Message Queue for MQTT broker, the application server returns the previously applied device access credential for local disaster recovery.
  4. The application server issues the requested device access credential to the corresponding Message Queue for MQTT client.
  5. The Message Queue for MQTT client sends an authentication request to connect to the Message Queue for MQTT broker. The relevant parameters in the authentication request are configured by using the information contained in the device access credential based on the predefined rules. After the Message Queue for MQTT client passes the authentication, it can send and receive messages.

Limits

Limits on instance specifications

  • The quota of device access credentials is equal to the maximum number of connections that is specified when you create an instance. When the upper limit is reached, you cannot apply for access credentials for new devices. You can upgrade the instance specifications to increase the quota of device access credentials. For more information, see Renew an instance and upgrade or downgrade the configurations of an instance.
  • When you use the unique-certificate-per-device authentication mode, we recommend that you call the UnRegisterDeviceCredential operation to delete device access credentials that are no longer used at the earliest opportunity to save the quota.

Limits on Message Queue for MQTT clients

  • A Message Queue for MQTT client includes the UserName and Password parameters in the authentication request each time it establishes a connection to a Message Queue for MQTT broker. Make sure that the UserName and Password parameters are configured by using the AccessKey ID and AccessKey secret in the device access credential based on the predefined rules.
  • The Message Queue for MQTT client must persistently store the device access credential that is returned by the application server. This eliminates the need to apply for the same device access credential each time the client reconnects to the Message Queue for MQTT broker. This can avoid the application server from unexpectedly quitting when a large number of Message Queue for MQTT clients connect to the Message Queue for MQTT broker at the same time.

Limits on application servers

  • The application server must manage mappings between device access credentials and Message Queue for MQTT clients. This eliminates the need to repeatedly call the credential application operation for the same client.
  • The application server must implement local disaster recovery. This can ensure business continuity in scenarios in which the Message Queue for MQTT broker becomes temporarily unavailable.

Related API operations

You can call corresponding API operations to perform unique-certificate-per-device authentication. An application server applies for and manages device access credentials. It sends API requests over HTTPS to interact with a ApsaraMQ for MQTT broker.

Each API operation requires identity verification that is performed by using an AccessKey pair and a request signature. Message Queue for MQTT provides API operations that allow you to create, query, delete, and update device access credentials. For more information about the API operations, see Unique-certificate-per-device authentication operations.