tencent cloud

Configuring Data Plane Authorization
Download PDF
Last updated:2026-01-30 14:55:29
Configuring Data Plane Authorization
Last updated: 2026-01-30 14:55:29
Download PDF

Basic Concepts

Authorization controls permissions for MQTT client operations including CONNECT, PUBLISH, and SUBSCRIBE. When an MQTT client connects, publishes, or subscribes, the MQTT server queries the authorization data source, matches the queried access control rules with the action to be performed, and confirms whether to allow or deny this operation based on the matching result.
Access control statements logically consist of four parts: Access, Actions, Topics, and Condition.
Domain
Field Name
Example Value
Required
Decision
effect
allow/deny
Yes
Operation
actions
["connect", "pub", "sub"]
Yes
Resource
topics
["home/room1/*", "sensor/temperature/0"]
No
Conditions
clientId
"sensor*"
No
username
"user*"
No
qos
[0, 1, 2]
No
retain
true/false
No
ip
client IP address: 10.0.0.1 or CIDR 10.0.0.0/16
No
MQTT instances provide database-based policy storage sources by default. You can define, update, sort, and delete policies via the console or TencentCloud API. Policy modifications take effect after regular synchronization to MQTT nodes.

Working Principles

Authorization Chain

In addition to the built-in database-based access control source, ACL based on JWT claim is also supported. Multiple authorizers jointly compose an authorization chain. When a client performs an operation, it matches sequentially according to the authorization chain until obtaining the decision result.

Each authorizer can define zero or more authorization policies. The authorizer sequentially matches the current client operation (Actions), operation resource (Topics), and client information (Client ID, Username, certificate information) with the policy rules in the defined order.
When a policy rule of the authorizer matches, the client operation is allowed or denied based on the rule's decision, and the authorization chain matching ends.
When a policy rule does not match, attempt to match the next rule defined in the authorizer.
When all rules of the authorizer do not match, pass to the next authorizer for matching.
When all authorizers finish matching and no rule is matched, deny the client request by default.

Policy Variable

Topic, ClientId, and Username support the following policies. When the authorizer executes a matching operation, it will replace ${PolicyVariable} with the actual value before and then proceed with the match.
Variable Name/Policy Variable
Semantics
Username
MQTT client connection Username.
ClientId
MQTT Client ID.
Certificate.Subject.Country
One cert per device in the scenario of country information. For details, see RFC4519.
Certificate.Subject.Organization
Organization information for one cert per device in the scenario. For details, see RFC4519.
Certificate.Subject.OrganizationalUnit
Organizational unit information for one cert per device in the scenario. For details, see RFC4519.
Certificate.Subject.State
Province and municipality information for one cert per device in the scenario. For details, see RFC4519.
Certificate.Subject.CommonName
CommonName for one cert per device in the scenario. For details, see RFC4519.
Certificate.Subject.SerialNumber
Certificate serial number for one cert per device in the scenario. For details, see RFC4519.

Policy Wildcard

Topics Field

Topics field supports the following wildcards:
Wildcard
Semantics
+
Consistent with the MQTT protocol Topic Filter Wildcard.
#
Aligns with the MQTT protocol Topic Filter Wildcard.
?
Any character.
*
Any characters.

ClientId, Username Fields

Wildcard
Semantics
?
Any character.
*
Any characters.

Policy Cache

Based on the characteristics of the authorizer, the MQTT server may cache policy rules to speed up policy retrieval. Therefore, changes made via the console or TencentCloud API require a cache update for the changes to take effect.

Policy sequence

The policy order impacts the final result of the authorizer chain. When defining multiple policy rules, ensure the authorization sequence meets business requirements.

Prerequisites

The Pro Edition supports configuration of up to 20 authorization policies, while the Platinum Version supports configuration of up to 30 authorization policies.
When authorization policy is not enabled, there are no permission restrictions on data plane resources. Any "username + password" can connect, produce and consume.

Configuring Authorization Policies

Creating Policies

1. Log in to the MQTT Console.
2. Click Resource > Cluster in the left sidebar. After selecting a region, click the "ID" of the target cluster to enter the cluster basic information page.
3. On the cluster details page, select the Authorization Policy tab, click Enable Authorization Policy Management, then click Confirm in the pop-up to complete the authorization policy setup.
4. Click Create Policy in the top-left corner and fill in the policy information.
Setting
Description
Policy Name
Set policy name. Comply with naming rule: 3-64 characters, support Chinese, letters, numbers, "-" and "_".
Description
Optional. Should not exceed 128 characters.
Creation Method
Supports visualization of policy settings and JSON file configuration.
Effect
"Allow" or "Deny". If selected "Allow", it means that the client operation can be used when the configured conditions are met. If selected "Deny", the client operation will be rejected when the configured conditions are met.
Operation
The authorization policy targets different requests, including Connect, Publish, and Subscribe, supporting multiple selections.
Topic
Supports the use of wildcards and Policy variables. For details, see Expression Description.
Username
Optional. Fill in a single username or resource expression. Wildcards and Policy variables are supported. For details, see Expression Description. Leave blank to support all users.
Client ID
Optional. Fill in a single resource expression. Wildcards and Policy variables are supported. For details, see Expression Description. Leave blank or enter * to support all clients.
IP Address
Optional. Only supports filling in a single IP (e.g., 192.168.0.1) or CIDR format (e.g., 192.168.1.0/24).
QoS
Select the authorized policy-supported QoS level.
Message retention
Select whether the authorization policy supports message retention. Check all to support all messages.

5. Click Submit, then confirm OK in the pop-up to complete the creation and return to the authorization policy list page.
6. On the strategy list page, you can manually adjust the policy order. The server authenticates according to the current policy sequence. If policy settings conflict, the higher sorting order takes precedence.

Replication Strategy

When a large number of similar policy tasks need to be created, you can click Copy policy in the operation column of the created policy. Simply adjust the points of difference to complete policy creation, effectively improving configuration efficiency for similar policies.

Policy Examples

Allow All Client Operations


{
    "effect": "allow",
    "actions": [
        "connect",
        "pub",
        "sub"
    ],
    "topics": [
        "*"
    ],
    "condition": {
        "ip": "0.0.0.0/0",
        "clientId": "",
        "username": "",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Deny All Client Operations


{
    "effect": "deny",
    "actions": [
        "connect",
        "pub",
        "sub"
    ],
    "topics": [
        "*"
    ],
    "condition": {
        "ip": "0.0.0.0/0",
        "clientId": "",
        "username": "",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Allow All Clients to Publish Messages to a Topic

{
    "effect": "allow",
    "actions": [
        "connect",
        "pub"
    ],
    "topics": [
        "topicA/test"
    ],
    "condition": {
        "ip": "0.0.0.0/0",
        "clientId": "",
        "username": "",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Allow All Clients to Publish Messages to Multiple Topics

{
    "effect": "allow",
    "actions": [
        "connect",
        "pub"
    ],
    "topics": [
        "home/sensor", "device/1"
    ],
    "condition": {
        "ip": "0.0.0.0/0",
        "clientId": "",
        "username": "",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Allow Clients to Send to Any Sub Topic

{
    "effect": "allow",
    "actions": [
        "connect",
        "pub"
    ],
    "topics": [
        "home/#", "device/+"
    ],
    "condition": {
        "ip": "0.0.0.0/0",
        "clientId": "",
        "username": "",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Allowing Clients to Send to Specified Prefix, Suffix Topic

{
    "effect": "allow",
    "actions": [
        "connect",
        "pub"
    ],
    "topics": [
        "prefix*", "*suffix"
    ],
    "condition": {
        "ip": "0.0.0.0/0",
        "clientId": "",
        "username": "",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Allow Client-Id Containing Username Client Connection

{
    "effect": "allow",
    "actions": [
        "connect"
    ],
    "topics": [
        "*"
    ],
    "condition": {
        "ip": "0.0.0.0/0",
        "clientId": "*${Username}*",
        "username": "",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Reject Client Connection with Root in Username

{
    "effect": "deny",
    "actions": [
        "connect"
    ],
    "topics": [
        "*"
    ],
    "condition": {
        "ip": "0.0.0.0/0",
        "clientId": "*",
        "username": "*root*",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Only Allow Client IP in Specified IP Range to Subscribe to Messages

{
    "effect": "allow",
    "actions": [
        "connect", "sub"
    ],
    "topics": [
        "*"
    ],
    "condition": {
        "ip": "192.168.0.0/16",
        "clientId": "*",
        "username": "*",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Clients with ClientId Matching BYOC Cert CommonName Allow Sending Subscribe Specific Message

{
    "effect": "allow",
    "actions": [
        "connect", "pub", "sub"
    ],
    "topics": [
        "home/${Username}/+", "sensor/${ClientId}/#"
    ],
    "condition": {
        "ip": "192.168.0.0/16",
        "clientId": "*${Certificate.Subject.CommonName}*",
        "username": "*",
        "qos": [
            0,
            1,
            2
        ],
        "retain": [
            "true",
            "false"
        ]
    }
}

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback