Topic spaces in the Azure Event Grid MQTT broker

A topic space represents multiple topics through a set of topic templates. Topic templates extend MQTT topic filters with support for variables, in addition to the standard MQTT wildcards. Each topic space represents the MQTT topics that the same set of clients use to communicate.

Topic spaces simplify access control by letting you grant publish or subscribe access to a group of topics at once, instead of managing access for each individual topic. The access control model combines four resources to grant a client group access to publish or subscribe to a topic space:

• Client: Represents a device or application that communicates over MQTT.
• Client group: Groups the clients that need the same access to the same set of MQTT topics.
• Topic space: Groups one or more topic templates that represent the intended topics or topic filters.
• Permission binding: Grants a client group publish or subscribe access to a topic space.

For more information, see Access control for MQTT clients.

This article explains how MQTT topic filters, topic templates, and topic space configuration work together, so that you can group related topics and manage client access efficiently.

MQTT topic filters

An MQTT topic filter is an MQTT topic that can include wildcards for one or more of its segments, so that it matches multiple MQTT topics. Topic filters simplify subscription requests, because one topic filter can match multiple topics.

The MQTT broker supports all the MQTT wildcards defined by the MQTT specification:

• + matches a single segment. For example, the topic filter machines/+/alert matches these topics:
  • machines/temp/alert
  • machines/humidity/alert
• # matches zero or more segments at the end of the topic. For example, the topic filter machines/# matches these topics:
  • machines
  • machines/temp
  • machines/humidity
  • machines/temp/alert

For more information about wildcards, see Topic wildcards in the MQTT specification.

Topic templates

Topic templates extend MQTT topic filters with support for variables, in addition to the MQTT wildcards. Topic space configuration also provides granular access control by letting you control the authorization of each client within a client group to publish or subscribe to its own topic. For more information, see how topic templates provide granular access control.

Topic space configuration

A topic space can group up to 10 topic templates. Topic templates support the MQTT wildcards (+ and #) and the following variables:

• ${client.authenticationName}: Represents the authentication name of the client. For more information, see key terms of client metadata.
• ${client.attributes.x}: Represents an attribute assigned to a client when the client is created or updated, where x is the exact string of the attribute key. For example, if a client has the attribute area:section1, the topic template area/${client.attributes.area}/telemetry enables only clients with that attribute to publish on the MQTT topic area/section1/telemetry. For more information, see MQTT clients.

To create a topic space in the Azure portal or with the Azure CLI, see Publish and subscribe to MQTT messages. When you name a topic space, use these rules:

• A topic space name can be 3-50 characters long.
• A topic space name can include alphanumeric characters and hyphens (-), with no spaces.

The following Azure CLI example creates a topic space that has two topic templates:

az eventgrid namespace topic-space create -g myRG --namespace-name myNS -n myTopicSpace --topic-templates ['segment1/+/segment3/${client.authenticationName}', "segment1/${client.attributes.attribute1}/segment3/#"]

Related content

• Publish and subscribe to MQTT messages
• Access control for MQTT clients
• MQTT clients
• MQTT client authentication