Edit

Share via

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

  • Article

In this article, you use the Azure portal to do the following tasks:

  1. Create an Event Grid namespace and enable MQTT broker
  2. Create sub resources such as clients, client groups, and topic spaces
  3. Grant clients access to publish and subscribe to topic spaces
  4. 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 may 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.

    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.

    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.

    step certificate fingerprint client1-authn-ID.pem

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

    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.

    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.

    Screenshot of searching for Event Grid namespace on Azure portal.

  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.

      Screenshot showing Event Grid namespace create flow basics tab.

  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.

    Screenshot showing Event Grid namespace configuration page to enable MQTT.

Create clients

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

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

    Screenshot of the Clients page with Add button selected.

  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.

    Screenshot of client 1 configuration.

  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.

    Screenshot of client 2 configuration.

    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.

    Screenshot of Topic spaces page with create button selected.

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

  4. Select + Add topic template.

    Screenshot of Create topic space with the name.

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

    Screenshot of topic space configuration.

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.

    Screenshot that shows the Permission bindings page with the Create button selected.

  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.

      Screenshot showing creation of first permission binding.

  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.

    Screenshot showing creation of second permission binding.

  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/.

    Screenshot showing MQTTX app left rail to add new client.

  2. 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.

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

    Screenshot showing Event Grid namespace overview page, which has MQTT hostname.

  4. Update the port to 8883.

  5. Toggle SSL/TLS to ON.

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

  7. Select Certificate as Self signed.

  8. Provide the path for client certificate file.

  9. Provide the path for the client key file.

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

    Screenshot showing client 1 configuration part 1 on MQTTX app.

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

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

    Screenshot showing client 2 configuration part 1 on MQTTX app.

    Screenshot showing client 2 configuration part 2 on MQTTX app.

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.

    Screenshot showing subscription topic configuration on MQTTX app.

  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.

    Screenshot showing message publishing on the topic in MQTTX app.

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

    Screenshot showing message published on the topic in MQTTX app.

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

    Screenshot showing the message received by the subscribing client on MQTTX app.

Next steps