ApsaraMQ for MQTT:Custom authentication

Glossary

Usage notes

All authentication methods involve two basic functions: identity authentication and resource permissions. Identity authentication verifies a client's identity based on the `Username`, `Password`, and `ClientId` parameters. Resource permissions refer to the permissions to publish to and subscribe to topics. You must upload authorization information to the server. The server then verifies the client's permissions for the topics used to send and receive messages.

Identity authentication

The server provides two dimensions for identity authentication:

• Based on the username. The ClientId is ignored, and multiple clients can share the same username.

• Based on the combination of username and ClientId. This identifies a specific client, and the identity cannot be used by other clients.

The `Password` parameter can be a key or a signature. Instead of using a raw key directly, you can generate the password by signing the ClientId with a key.

For example, if a client has the Client ID `GID_Test@@@0001` and uses the AccessKey secret `XXXXX`, you can use `XXXXX` as the key and the HMAC-SHA1 algorithm to sign the string `GID_Test@@@0001`. This produces a binary array. You can then Base64-encode the binary array to obtain the final password string.

However, to provide flexibility for different signature algorithms, you can also set a raw signature. The server then compares the password with the raw signature that you previously uploaded.

Resource permissions

Resources are primarily topics. ApsaraMQ for MQTT supports multi-level topics, but you must create parent topics in the console. Permissions are the rights to publish to and subscribe to topics. Before a client can exchange messages, you must grant permissions for the relevant topics. You can grant permissions for specific multi-level topics or using wildcard characters. You can grant these permissions to a username or a specific client (ClientId).

Connection blacklist

The custom authentication mode includes a connection blacklist feature. You can use this feature to block connections from a specific client (ClientId).

Process

The process is as follows:

1. The application server calls the relevant OpenAPI operations to upload identity information, such as username and password, and topic authorization information to the ApsaraMQ for MQTT server.

2. The application server sets the required client parameters, such as Username, Password, and ClientId.

3. The client sends a request to the ApsaraMQ for MQTT server. After the client is authenticated, it uses the corresponding topics to send and receive messages.

Limits

• Instance editions: Custom authentication is available only for Professional Edition and Platinum Edition instances.

• Expiration settings: ApsaraMQ for MQTT does not provide an expiration setting feature for data such as identity authentication, resource authorization, and connection blacklists. You can manage this data by calling the relevant operations to delete it when it is no longer required.

• Capacity: Both identity authentication and resource permission data consume metadata storage on the instance. Therefore, you must manage your authentication data and promptly delete data that is no longer required. The total number of identity authentications and resource permissions cannot exceed the connection limit of your instance. The connection blacklist is a type of permission data, and its count is included in the resource permission limit. For more information about connection limits, see Limits.

Group downgrade

ApsaraMQ for MQTT uses groups to identify a set of nodes that share the same logic and features. A group represents a class of devices with the same functions. A ClientId consists of two parts in the format <GroupID>@@@<DeviceID>. However, this format makes it difficult to migrate existing custom device IDs. To address this, ApsaraMQ for MQTT supports group downgrade. This feature lets you use any string for the ClientId. When group downgrade is active, some console features, such as device query and device trace query, are temporarily unavailable. To enable this feature, submit a ticket.

Related APIs

Custom authentication provides management APIs for identity authentication and resource authorization. The identity authentication APIs manage identity information, and the resource authorization APIs manage permissions for sending and receiving messages on topics.