Custom authentication

Key concepts

How it works

Custom authentication covers two functions:

• Identity authentication -- verifies who the client is, based on username, password, and optionally client ID.

• Resource authorization -- controls which topics the client can publish to or subscribe to.

A connection blacklist provides a third layer of control to block specific clients entirely.

The end-to-end flow works as follows:

1. Upload credentials and permissions. Your application server calls OpenAPI operations to upload identity information (username and password) and topic authorization rules to the ApsaraMQ for MQTT server.

2. Configure the MQTT client. Set the Username, Password, and ClientId parameters on the client based on the credentials uploaded in step 1.

3. Connect and exchange messages. The client sends a CONNECT request to the ApsaraMQ for MQTT server. The server verifies the client's identity and checks topic permissions. If authentication fails, the server rejects the connection. If authorization fails for a specific topic, the server denies the publish or subscribe operation on that topic. After successful verification, the client can publish and subscribe on authorized topics.

Identity authentication

The server supports two modes of identity verification:

import hmac
import hashlib
import base64

client_id = "GID_Test@@@0001"
secret_key = "XXXXX"

# Generate HMAC-SHA1 signature
signature = hmac.new(
    secret_key.encode("utf-8"),
    client_id.encode("utf-8"),
    hashlib.sha1
).digest()

# Base64-encode to get the final password
password = base64.b64encode(signature).decode("utf-8")
print(password)

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class MqttPasswordGenerator {
    public static String generatePassword(String clientId, String secretKey) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA1");
        mac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA1"));
        byte[] signature = mac.doFinal(clientId.getBytes("UTF-8"));
        return Base64.getEncoder().encodeToString(signature);
    }

    public static void main(String[] args) throws Exception {
        String password = generatePassword("GID_Test@@@0001", "XXXXX");
        System.out.println(password);
    }
}

Resource authorization

Grant explicit topic permissions before a client can publish or subscribe. ApsaraMQ for MQTT supports multi-level topics, but parent topics must be created in the console first.

Connection blacklist

Block a specific client by adding its ClientId to the connection blacklist. Blacklisted clients cannot connect until removed from the list.

Connection blacklist entries count toward the resource permission limit. For details, see Limitations.

Limitations

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

• No built-in expiration: Identity, authorization, and blacklist records do not expire automatically. Delete entries that are no longer needed by calling the corresponding API operations.

• Capacity: Identity authentication records and resource permission records both consume metadata storage on your instance. The combined total cannot exceed the connection limit of your instance. Connection blacklist entries count as resource permissions. For specific values, see Limits.

Group downgrade

By default, a ClientId follows the format <GroupID>@@@<DeviceID>, where the group identifies a class of devices with shared logic. This format can make it difficult to migrate device IDs that do not follow the convention.

Group downgrade removes this restriction and lets you use any string as the ClientId.

To enable group downgrade, submit a ticket.

API reference

Manage custom authentication data through the following API operations.