HTTP authentication

How it works

1. An MQTT client sends a CONNECT request to the ApsaraMQ for MQTT server.

2. The server extracts username, password, and clientId from the CONNECT message, then sends an HTTP POST request to your configured authentication endpoint.

3. Your HTTP service validates the credentials and returns a JSON response containing the authentication result and optional ACL rules.

4. If the result is allow, the client connects. The server enforces the returned ACL rules on all subsequent publish and subscribe operations.

5. If the result is deny, or the HTTP service returns a non-200 status code (4xx, 5xx), the client connection is rejected.

Prerequisites

Before you begin, make sure you have:

• An Enterprise Platinum Edition or Professional Edition instance in the Hangzhou, Shanghai, or Beijing region.

• HTTP authentication enabled on the whitelist for your instance.

• An HTTP authentication service is deployed within the VPC. The security group of the ECS instance hosting the HTTP authentication service must allow inbound traffic from the VPC CIDR block on the corresponding port. Do not allow 0.0.0.0/0. A deny policy is automatically created.

Build your HTTP authentication service

Your HTTP service must accept POST requests and return JSON responses that follow the contract below.

{
  "result": "allow",
  "expireAt": 1234,
  "acl": [
    {
      "effect": "allow",
      "action": ["publish", "subscribe"],
      "topic": "topic/abc/#"
    },
    {
      "effect": "deny",
      "action": ["publish"],
      "topic": "topic/abcd"
    }
  ]
}

Enable HTTP authentication

1. Log on to the ApsaraMQ for MQTT console.

2. In the left-side navigation pane, click Instances.

3. In the top menu bar, select the target region. In the instance list, click the instance name.

4. In the left-side navigation pane, click HTTP Authentication.

   Note

   The first time you open the HTTP Authentication page, you are prompted to create the AliyunServiceRoleForMqttTunnel service-linked role. Click OK. The system automatically creates this role, which establishes the network channel required for HTTP authentication.

5. On the HTTP Authentication page, configure the following settings:

   Parameter	Description
   HTTP Authentication	Turn on the switch.
   Request Method	Fixed to POST.
   URL	The endpoint of your HTTP authentication service. We recommend that you use a VPC internal endpoint.
   VPC	The VPC where your HTTP authentication service is deployed.
   vSwitch	Select a vSwitch in each availability zone. These vSwitches create the network channels between the MQTT server and your HTTP service.

6. Configure the request parameters.

   Headers:

   Parameter	Value	Description
   Content-Type	application/json	Fixed. Cannot be modified.

   Body:

   Parameter	Value	Description
   username	${username}	Populated at runtime from the Username field of the CONNECT message. Cannot be modified.
   password	${password}	Populated at runtime from the Password field of the CONNECT message. Cannot be modified.
   clientId	${clientId}	Populated at runtime from the client ID. Cannot be modified.
   token	Custom value	Optional. A custom token your HTTP service can use to verify that the request originated from the MQTT server.

7. Configure timeout settings.

   Parameter	Description
   Connection Timeout	Time to wait for a connection to your HTTP service. Range: 1 to 5 seconds. Default: 5 seconds.
   Request Timeout	Time to wait for a response from your HTTP service. Range: 1 to 5 seconds. Default: 5 seconds.

8. Click OK in the upper-left corner of the page. The system creates the network channel. This takes 1 to 3 minutes. After the channel is ready, click the test button next to the URL to verify connectivity.

Disable HTTP authentication

1. Log on to the ApsaraMQ for MQTT console.

2. In the left-side navigation pane, click Instances.

3. In the top menu bar, select the target region. In the instance list, click the instance name.

4. In the left-side navigation pane, click HTTP Authentication.

5. On the HTTP Authentication page, turn off the HTTP Authentication switch.

6. Click OK in the upper-left corner of the page. The system deletes the network channel. This takes 1 to 3 minutes.

Group downgrade

In ApsaraMQ for MQTT, a Group represents a class of devices or nodes with the same functionality. By default, the client ID must follow the format <GroupID>@@@<DeviceID>.

If you are migrating from a self-managed broker and your devices already use custom client IDs that do not match this format, enable the Group ID fallback feature. With this feature enabled, the client ID can be any string.

Limits

Billing

HTTP authentication is in public preview and free of charge. Transactions per second (TPS) are metered, and the maximum TPS depends on your instance specifications.