Content

IoTDA provides device topic policies, with which you can authorize clients to publish or subscribe to messages through custom topics not starting with $oc, enhancing communications security. Device policies are mainly used for protocols used in data publishing and subscription mechanisms, for example, MQTT and MQTTS on the device side. Currently, this feature is available for users in invitation-only regions of south China.

Policy Wildcards

You can use wildcards for policies. An asterisk (*) indicates any combination of characters, and a question mark (?) indicates a character of any kinds. Plus signs (+) and number signs (#) do not have special meanings.

**Table 1** Policy wildcards
Wildcard	MQTT Wildcard	Applicable to Policy	Example MQTT Topic	Example MQTT Topic for Policy
#	Yes	No	test/#	Not applicable. The number sign (#) is regarded as a character without special meaning.
+	Yes	No	test/+/some	Not applicable. The plus sign (+) is regarded as a character without special meaning.
*	No	Yes	Not applicable. The asterisk (*) is regarded as a character without special meaning.	test/* test/*/some
?	No	Yes	Not applicable. The question mark (?) is regarded as a character without special meaning.	test/????/some test/set?????/some

**Table 2** Example usage of wildcards in policies
Target Topic	Topic Definition in Policy	Description
Example topics: test/topic1/some test/topic2/some test/topic3/some	topic:test/topic?/some	Common points: test/topic + a character + /some. In the policy definition, a question mark (?) indicates a character. Therefore, the policy topic can be defined as topic:test/topic?/some.
Example topics: test/topic1/pub/some test/topic2/sub/some test/topic3/some	topic:test/topic*/some	Common points: test/topic + one or more characters + /some. In policy definition, the asterisk () indicates multiple or one character. Therefore, the policy topic can be defined as topic:test/topic/some**.

Policy Variables

You can use a policy variable as a placeholder for resource or condition key to filter topics when defining policy resource. During MQTT topic verification, the system replaces the variable with the corresponding ID for matching.

Variables are prefixed with a dollar sign ($), followed by a pair of braces ({}), which contain the variable name in the request. The following table lists the supported variables. Assume that the client ID of an MQTT device is test_clientId, the product ID is test_productId, and the device ID is test_deviceId.

**Table 3** Policy variables
Policy Variable	Description	Example MQTT Topic	Example MQTT Topic for Policy
${devices.deviceId}	Device ID	test/test_deviceId/topic	test/${devices.deviceId}/topic
${devices.clientId}	Client ID	test/test_clientId/topic	test/${devices.clientId}/topic
${devices.productId}	Product ID	test/test_productId/topic	test/${devices.productId}/topic

**Table 4** Example usage of variables in policies
Scenario	Example Policy Topic Definition	Description
Distinguishing topics by device	test/${devices.deviceId}/topic	Devices can subscribe to or publish messages through topic test/${Device ID}/topic with their data isolated.
Distinguishing topics by device and time segment	test/${devices.clientId}/topic	Devices can subscribe to or publish messages through topic test/${Device client ID}/topic. Different from deviceId, clientId carries a timestamp to distinguish time segments.

Policy Priority

If multiple policies with different effect are bound to the same device, the policy with higher priority (Denied over Allowed) takes effect.

For example, a device has two policies: policy 1 and policy 2. Policy 1 denies subscription to topic A, and policy 2 allows subscription to topic A. When the device subscribes to topic A, the platform rejects the subscription request from the device.

**Table 5** Policy priority
Topic	Policy 1	Policy 2	Effective Policy
test/topic	"effect": "ALLOW", "resources": ["topic:test/topic" ]	"effect": "DENY", "resources": ["topic:test/topic" ]	Denied

Policy Topic Constraints

Max. length: 128 bytes.
Unallowed wildcards for topic publishing: number signs (#) and plus signs (+).
Consecutive slashes (/) are not allowed, for example, ////test/.
Max. slashes (/) in a topic: 7.

If the topic to be published or subscribed to does not meet the preceding requirements, the subscription or publishing request will be rejected. On the device details page, choose the Message Trace tab. The error information is displayed.

Figure 1 Message tracing - Verifying a policy
Click to enlarge