Quickstart: Publish and subscribe to MQTT messages on Event Grid Namespace with Azure portal

In this quickstart, you use the Azure portal to create an Event Grid namespace with MQTT broker enabled, create sub resources such as clients, client groups, and topic spaces, grant clients access to publish and subscribe to topic spaces, and then publish and receive messages between clients.

Prerequisites

• Create an Azure free account If you don't have an Azure subscription.
• Read through Event Grid overview before starting this tutorial, if you're new to Azure Event Grid.
• Ensure that port 8883 is open in your firewall. The sample in this tutorial uses the MQTT protocol, which communicates over port 8883. This port might be blocked in some corporate and educational network environments.
• You need an X.509 client certificate to generate the thumbprint and authenticate the client connection.

Generate sample client certificate and thumbprint

If you don't already have a certificate, you can create a sample certificate using the step CLI. Consider installing manually for Windows.

After a successful installation of Step, you should open a command prompt in your user profile folder (Win+R type %USERPROFILE%).

1. To create root and intermediate certificates, run the following command. Remember the password, which needs to be used in the next step.

   PowerShell

   step ca init --deployment-type standalone --name MqttAppSamplesCA --dns localhost --address 127.0.0.1:443 --provisioner MqttAppSamplesCAProvisioner
   

2. Use the CA files generated to create a certificate for the first client. Ensure to use the correct path for the cert and secrets files in the command.

   PowerShell

   step certificate create client1-authn-ID client1-authn-ID.pem client1-authn-ID.key --ca .step/certs/intermediate_ca.crt --ca-key .step/secrets/intermediate_ca_key --no-password --insecure --not-after 2400h
   

3. To view the thumbprint, run the Step command.

   PowerShell

   step certificate fingerprint client1-authn-ID.pem
   

4. Now, create a certificate for the second client.

   PowerShell

   step certificate create client2-authn-ID client2-authn-ID.pem client2-authn-ID.key --ca .step/certs/intermediate_ca.crt --ca-key .step/secrets/intermediate_ca_key --no-password --insecure --not-after 2400h
   

5. To view the thumbprint to use with the second client, run the Step command.

   PowerShell

   step certificate fingerprint client2-authn-ID.pem
   

Create a namespace

1. Sign in to Azure portal.

2. In the search bar, type Event Grid Namespaces, and then select Event Grid Namespaces from the drop-down list.

   

3. On the Event Grid Namespaces page, select + Create on the toolbar.

4. On the Create namespace page, follow these steps:

   1. Select your Azure subscription.

   2. Select an existing resource group or select Create new and enter a name for the resource group.

   3. Provide a unique name for the namespace. The namespace name must be unique per region because it represents a DNS entry. Don't use the name shown in the image. Instead, create your own name - it must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and -.

   4. Select a location for the Event Grid namespace. Currently, Event Grid namespace is available only in select regions.

      

5. Select Review + create at the bottom of the page.

6. On the Review + create tab of the Create namespace page, select Create.

   Note

   To keep the QuickStart simple, you'll be using only the Basics page to create a namespace. For detailed steps about configuring network, security, and other settings on other pages of the wizard, see Create a Namespace.

7. After the deployment succeeds, select Go to resource to navigate to the Event Grid Namespace Overview page for your namespace.

8. In the Overview page, you see that the MQTT broker is in Disabled state. To enable MQTT broker, select the Disabled link, it will redirect you to Configuration page.

9. On Configuration page, select the Enable MQTT broker option, and then select Apply to apply the settings.

   

Create clients

1. On the left menu, select Clients in the MQTT broker section.

2. On the Clients page, select + Client on the toolbar.

   

3. On the Create client page, enter a name for the client. Client names must be unique in a namespace.

4. Client authentication name is defaulted to the client name. For this tutorial, change it to client1-authn-ID. You need to include this name as Username in the CONNECT packet.

5. In this tutorial, you use thumbprint based authentication. Include the first client certificate’s thumbprint in the Primary Thumbprint.

   

6. Select Create on the toolbar to create another client.

7. Repeat the above steps to create a second client named client2. Change the authentication name to client2-authn-ID and include the second client certificate’s thumbprint in the Primary Thumbprint.

   

   Note

   • To keep the QuickStart simple, you'll be using Thumbprint match for authentication. For detailed steps on using X.509 CA certificate chain for client authentication, see client authentication using certificate chain.
   • Also, we use the default $all client group, which includes all the clients in the namespace for this exercise. To learn more about creating custom client groups using client attributes, see client groups.

Create topic spaces

1. On the left menu, select Topic spaces in the MQTT broker section.

2. On the Topic spaces page, select + Topic space on the toolbar.

   

3. Provide a name for the topic space, on the Create topic space page.

   

4. Enter contosotopics/topic1 for the topic template, and then select Create to create the topic space.

   

Configuring access control using permission bindings

1. On the left menu, select Permission bindings in the MQTT broker section.

2. On the Permission bindings page, select + Permission binding on the toolbar.

   

3. Configure the permission binding as follows:

   1. Provide a name for the permission binding. For example, contosopublisherbinding.

   2. For client group name, select $all.

   3. For Topic space name, select the topic space you created in the previous step.

   4. Grant the Publisher permission to the client group on the topic space.

      

4. Select Create to create the permission binding.

5. Create one more permission binding (contososubscriberbinding) by selecting + Permission binding on the toolbar.

6. Provide a name and give $all client group Subscriber access to the ContosoTopicSpace as shown.

   

7. Select Create to create the permission binding.

Connecting the clients to the EG Namespace using MQTTX app

1. For publish / subscribe MQTT messages, you can use any of your favorite tools. For demonstration purpose, publish / subscribe is shown using MQTTX app, which can be downloaded from https://mqttx.app/.

2. Select + on the navigation bar to the left.

3. Configure client1 with

   • Name as client1 (this value can be anything)

   • Client ID as client1-session1 (Client ID in the CONNECT packet is used to identify the session ID for the client connection)

   • Username as client1-authn-ID. This value must match the value of Client Authentication Name that you specified when you created the client in the Azure portal.

     Important

     Username must match the client authentication name in client metadata.

4. Update the host name to MQTT hostname from the Overview page of the namespace.

   

5. Update the port to 8883.

6. Toggle SSL/TLS to ON.

7. Toggle SSL Secure to ON, to ensure service certificate validation.

8. Select Certificate as CA or Self signed certificates.

9. Provide the path for client certificate file.

10. Provide the path for the client key file.

11. Rest of the settings can be left with predefined default values.

    

12. Select Connect to connect the client to the MQTT broker.

13. Repeat the above steps to connect the second client client2, with corresponding authentication information as shown.

    

    

Publish/subscribe using MQTTX app

1. After connecting the clients, for client2, select the + New Subscription button.

2. Add contosotopics/topic1 as topic and select Confirm. You can leave the other fields with existing default values.

   

3. Select client1 in left rail.

4. For client1, on top of the message compose box, type contosotopics/topic1 as the topic to publish on.

5. Compose a message. You can use any format or a JSON as shown.

6. Select the Send button.

   

7. The message should be seen as published in client 1.

   

8. Switch to client2. Confirm that client2 received the message.

   

Related content

• Tutorial: Route MQTT messages to Azure Event Hubs using namespace topics
• Tutorial: Route MQTT messages to Azure Functions using custom topics
• For code samples, go to this repository.