MQTT HTTP authentication configuration guide-ApsaraMQ for MQTT(MQTT)-阿里云帮助中心

HTTP authentication allows ApsaraMQ for MQTT to authenticate connecting clients by calling an external HTTP authentication service that you provide, so that you can implement complex authentication and authorization logic. When a client connects, the MQTT server builds an HTTP request from the client information and determines the authentication result from the response of your HTTP authentication service. This mode is commonly used when you migrate from a self-managed broker to the cloud and want to keep your original permission check logic as much as possible.

How it works

Client connection

When an MQTT client sends a connection request to the MQTT server, the MQTT server acts as the request client. The MQTT server uses the client information to build an HTTP request in the format required by the API and sends the request to your HTTP authentication service. The HTTP authentication service verifies the client identity based on the request parameters and returns the authentication result. The MQTT server determines the authentication result based on the returned content.

Publish or subscribe

After a client connects, the MQTT server verifies permissions based on the access control list (ACL) rules in the HTTP response each time the client publishes a message or subscribes to a topic.

Limits

The following limits apply to HTTP authentication:

Item	Description
Supported editions	Only Platinum Edition and Professional Edition instances are supported.
Supported regions	Hangzhou, Shanghai, and Beijing. To use HTTP authentication in other regions, submit a ticket.
Number of HTTP authentication services	A single instance supports only one HTTP authentication service.
Number of ACL rules	A response contains no more than 10 ACL rules.
Response content size	The returned content does not exceed 4 KB.

Billing

HTTP authentication is in public preview and is free of charge. Transactions per second (TPS) is metered. The TPS upper limit is determined by your instance specifications.

Prerequisites

An ApsaraMQ for MQTT instance is created. For more information, see Create an instance. Make sure that the instance meets the edition and region requirements described in Limits.
The whitelist for the HTTP authentication feature is enabled. To use this feature, submit a ticket.
An HTTP authentication service is deployed in a VPC. The security group of the Elastic Compute Service (ECS) instance that hosts the HTTP authentication service allows the CIDR block of the VPC and the corresponding port. Do not allow 0.0.0.0/0, because a deny policy is created automatically.

Request and response format

This section describes the format of the authentication requests that the MQTT server sends to your HTTP authentication service and the responses that your service must return.

Request format

The MQTT server sends authentication requests by using the POST method. The Content-Type request header is fixed to application/json and cannot be modified.

The following table describes the parameters in the request body.

Parameter	Value	Description
`username`	`${username}`	Replaced at runtime with the `Username` field in the `CONNECT` message. Cannot be modified.
`password`	`${password}`	Replaced at runtime with the `Password` field in the `CONNECT` message. Cannot be modified.
`clientId`	`${clientId}`	Replaced at runtime with the client ID. Cannot be modified.
`token`	A custom value	An optional parameter that the HTTP authentication service uses to authenticate the identity of MQTT requests.

Response format

Your HTTP authentication service must meet the following requirements:

The Content-Type of the HTTP response must be application/json.
The authentication result is indicated by the result field in the response body. Valid values: allow and deny.
The authentication result must be returned with HTTP status code 200. Other status codes, such as 4xx and 5xx, indicate that the HTTP authentication request failed.
The following example shows a response body:

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

The following table describes the response parameters.

Parameter	Type	Required	Description
`result`	String	Yes	The authentication result. Valid values: `allow` and `deny`.
`expireAt`	Long	No	The expiration time of the authentication result. The value is a Unix timestamp in seconds.
`acl`	Array	No	The list of ACL rules, which is used for fine-grained publish and subscribe permission control.

The following table describes the parameters of an ACL rule.

Parameter	Type	Description
`effect`	String	The effect of the rule. Valid values: `allow` and `deny`.
`action`	Array	The operation type. Valid values: `publish` and `subscribe`.
`topic`	String	The topic matching rule. The wildcards `#` and `+` are supported.

Enable HTTP authentication

Log on to the ApsaraMQ for MQTT console.
In the left-side navigation pane, click Instances.
In the top menu bar, select the region where your instance resides, and then click the instance name in the instance list.
In the left-side navigation pane, click HTTP Authentication.
Note
The first time that you open the HTTP Authentication page, a dialog box appears and prompts you to create the AliyunServiceRoleForMqttTunnel service-linked role. Click OK. The system automatically creates the role, which provides the network channel feature for HTTP authentication. For more information, see Service-linked role.

On the HTTP Authentication page, configure the following parameters:

Parameter	Description
HTTP Authentication	Turn on the switch to enable the HTTP authentication feature.
Request Method	The HTTP request method. The value is fixed to `POST`.
URL	The URL of the HTTP authentication service. We recommend that you specify a VPC internal endpoint.
VPC	Select the VPC where the HTTP authentication service is deployed.
vSwitch	Select a vSwitch in each zone. One vSwitch is required in each zone to create the network channel.
Connection Timeout	The connection timeout period. Valid values: 1 to 5 seconds. Default value: 5 seconds.
Request Timeout	The request timeout period. Valid values: 1 to 5 seconds. Default value: 5 seconds.

Click OK in the upper-left corner of the page.
The system starts to create the network channel. This takes 1 to 3 minutes. After the network channel is created, you can click the test button on the right side of URL to verify network connectivity.

Disable HTTP authentication

Log on to the ApsaraMQ for MQTT console.
In the left-side navigation pane, click Instances.
In the top menu bar, select the region where your instance resides, and then click the instance name in the instance list.
In the left-side navigation pane, click HTTP Authentication.
On the HTTP Authentication page, click the HTTP Authentication switch to turn off the feature.
Click OK in the upper-left corner of the page.
The system starts to delete the network channel. This takes 1 to 3 minutes.