Skip to content

MindSphere MindConnect MQTT Broker

Overview

MindSphere MindConnect MQTT Broker authenticates the MQTT agents over TLS to publish and subscribe messages adhering to MQTT protocol. It is an alternative to the HTTP-based MindConnect Service.

The following port-protocol-authentication combination is supported by MindSphere MindConnect MQTT Broker:

EU1

Protocol Authentication TCP Port ALPN protocol
MQTT Client Certificate 8883 N/A
MQTT Client Certificate 4431 x-amzn-mqtt-ca

EU2

Protocol Authentication TCP Port
MQTT Client Certificate 8883

Broker URLs

MindSphere MindConnect MQTT Broker URL for eu1 platform:

  • mindconnectmqtt.eu1.mindsphere.io

MindSphere MindConnect MQTT Broker URL for eu2 platform:

  • <dynamic>.azure-devices.net

Note

For EU2 platform, the broker URL is known only while onboarding the agent. The steps for handling the broker URL are detailed later.

Architecture

A secure connection between MindSphere MQTT Broker and the agent is achieved using trusted certificates issued by Certification Authority (CA). MindSphere tenant administrator uploads the public certificate (usually with extension .pem) from the chosen Certificate Authority. It can also be a self-signed certificate. The native broker can access this certificate and it uses the certificate to authenticate the MindConnect MQTT agents. MindSphere accepts the certificate in multiple steps. The approach is governed by the underneath platform services and it influences slight variation in the approach for EU1 and EU2.

EU1

CA certificates can be uploaded or deleted from MindSphere by tenant administrators. The asset manager application provides the user interface supporting these operations. There can be a maximum of two such certificates. Before accepting the certificate, MindSphere verifies the certificate. These certificates are used for the authentication of the agents. Agent certificate (X.509) can only be created using one of the two validated certificates. Otherwise, the agents will not be authenticated. The first time the agent is authenticated, it is provisioned by MindSphere. Its instance can be then found in Asset Manager.

image info

EU2

The same CA certificate management and agent certificate issuing apply to eu2 as well. Differently from eu1, agents of eu2 first need to connect to Azure DPS service with global DPS URL. After completing the DPS communication steps, DPS provides the broker URL to which agents can connect to.

image info

After successful onboarding, agents can publish and subscribe to topics. MindSphere has already defined topics that the agents can use to publish and subscribe. They can be found in the API documentation.

Security

MindSphere MQTT Broker uses Transport Layer Security (TLS) to secure connections from IoT agents. Currently supported versions are 1.0, 1.1 and 1.2 TLS. To prevent any connection problem in the future, use TLS 1.2 as the only TLS version when connecting to MindSphere MQTT Broker.

MindSphere MQTT Broker's Server Certificates

MindSphere MindConnect MQTT Broker uses different server certificates for eu1 and eu2. These certificates are required by the agents to securely communicate with the Broker. This should be downloaded from your respective tenant.

For more information, see Managing CA Certificates documentation.

Note

Due to a security report, Microsoft will start using DigiCert Global G2 Root instead of the currently using Baltimore CyberTrust Root as Certificate Authority (CA). The transition will start on June 2022 and end on October 2022. It is recommended to install both certificates as trusted CAs to avoid related connectivity issues. More details regarding this topic can be found here.

Server Name Indication

MindSphere MQTT Broker uses the server name indication (SNI) TLS extension for eu1. Agents must use this extension when they connect.

Onboarding

Agents can get onboarded to MindSphere using agent certificates that are issued by the owner tenant's CA certificate.

Definition of ClientId

To successfully connect, onboard, and communicate with the MQTT broker, each client needs to use a client id in the following format:

For eu1: <clientId> = <tenant>_<AgentCertificate.Subject.CommonName>

AgentCertificate.Subject.CommonName should only contain agent name (e.g. MQTTAgent01)

For eu2: <clientId> = <AgentCertificate.Subject.CommonName>

AgentCertificate.Subject.CommonName should be combination of tenant id and agent name (e.g. Siemens_MQTTAgent01)

MindSphere MQTT Broker provides Zero Touch Onboarding. Once the agent made a connect request to MindSphere MQTT Broker with valid certificates, Agent related resource will be created on MindSphere.

Prerequisites

  • Valid CA certificate should be present in MindSphere. Replace <tenantId> with actual tenant name in the following URLs.
  • In order to upload CA Certificate for EU1 from the following URL:

https://<tenantId>-assetmanager.eu1.mindsphere.io/connectivity/mqtt-certificates/upload-certificate

  • In order to upload CA Certificate for EU2 from the following URL:

https://<tenantId>-assetmanager.eu2.mindsphere.io/connectivity/mqtt-certificates/upload-certificate

  • During onboarding, agents should have ScopeId. After a successful CA Certificate upload operation, the customer can have ScopeId from MindConnect MQTT UI.
  • Agent certificate should be created.
    • In order to create agent certificate, see here for EU1.
    • In order to create agent certificate, see here for EU2.

Onboarding flow for EU1

MindSphere MQTT Broker expects agents to provide root certificate for TLS connection and agent certificate, agent key file and client id as MQTT Client Id for MQTT connection. Once agents made a connection request with a valid configuration, Agent resources on MindSphere will be created and MindSphere MQTT Broker will disconnect the agent from the broker. Agents should send another connect request after approximately 1 minute, after the next connect request, agents will be able to connect to the broker successfully.

Onboarding flow for EU2

MindSphere MQTT Broker expects agents to provide root certificate for TLS connection and agent certificate, agent key file and client id as MQTT Client Id for MQTT connection. Before connecting to the actual MQTT broker, each agent needs to connect to a global DPS (Device Provisioning Service) to register itself and get further MQTT broker parameters. Clients need to connect to the DPS MQTT broker using TLS with mutual authentication. To accomplish this, the client needs:

Registering Agent

Once connected to the DPS MQTT broker, the agent needs to be registered as follows: - SUBSCRIBE to the status topic $dps/registrations/res/#. The responses to requests made in the next steps will be received from this topic. - PUBLISH an empty message to $dps/registrations/PUT/iotdps-register/?$rid=1. This registers the agent and it will now be visible on MindSphere. A response object will be published by the DPS to the topic subscribed in the first step. It looks like this:

{
  "operationId": "<operationId>",
  "status": "assigning"
}
  • To get the status of registration, PUBLISH an empty message to $dps/registrations/GET/iotdps-get-operationstatus/?$rid=2&operationId=<operationId>. A response is published to the topic in the first step.
{
"operationId": "<operationId>",
  "status": "assigned",
  "registrationState": {
    "x509": {
      "enrollmentGroupId": "TenantEnrollmentGroup-TenantCACertificate-<tenant>"
    },
    "registrationId": "<clientId>",
    "createdDateTimeUtc": "2021-06-03T08:37:58.8521797Z",
    "assignedHub": "<Address of MindSphere MQTT Broker>",
    "deviceId": "<clientId>",
    "status": "assigned",
    "substatus": "initialAssignment",
    "lastUpdatedDateTimeUtc": "2021-06-03T08:37:59.1384561Z",
    "etag": "..."
  }
}

Connect to MindSphere MQTT Broker

After successful registration, the agent can connect to MindSphere MindConnect MQTT Broker. MindSphere MindConnect MQTT Broker URL can be found in the response of the registration message. Value of assignedHub is URL of MindConnect MQTT Broker.

Topic Structure

MindConnect MQTT Async APIs provide topics and message structures to create their assets, types, mappings and ingest timeseries data.

Models are templates describing asset/aspect types, asset instances, asset hierarchy and mappings from data point ids to variables in aspects.

Instantiations are the realization of models. An instantiation job takes a model and creates the items described in the model by creating types, instances and mappings. A model can be instantiated many times.

Complete Async API specifications can be found here:

EU1

<designator>/<tenantId>/<clientId>/<direction>/<app>_<version>/<app_topic>

<designator>: [tc]

  • tc: tenant-client topic structure

<tenantId>: tenant id

<clientId>: Unique client id.

<direction>: [i|o]

  • i: inbound. Clients can subscribe.
  • o: outbound. Clients can publish

<app>: Registered application topic name.

<version>: Version of application

<app_topic>: App specific sub topics.

PUBLISH : tc/<tenantId>/<clientId>/o/amo_v3/m

  • Models are templates describing asset/aspect types, asset instances, asset hierarchy and mappings from data point ids to variables in aspects.

SUBSCRIBE : tc/<tenantId>/<clientId>/i/amo_v3/ms

  • Receive model creation results for a previous model request.

PUBLISH : tc/<tenantId>/<clientId>/o/amo_v3/i

  • Instantiations are the realization of models. An instantiation job takes a model and creates the items described in the model by creating types, instances and mappings. A model can be instantiated many times.

SUBSCRIBE : tc/<tenantId>/<clientId>/o/amo_v3/ip

  • Receive instantiation job results for a previous instantiation request.

EU2

Topic Structure for PUBLISH

devices/<clientId>/messages/events/<propertyBag>

<clientId>: Unique client id.

<propertyBag>: Property bag should contain application topic name, version and application specific sub topic.

Topic Structure for SUBSCRIBE

devices/<clientId>/messages/devicebound/#

<clientId>: Unique client id.

PUBLISH : devices/<clientId>/messages/events/amo_v3=m

  • Models are templates describing asset/aspect types, asset instances, asset hierarchy and mappings from data point ids to variables in aspects.

PUBLISH : devices/<clientId>/messages/events/amo_v3=i

  • Instantiations are the realization of models. An instantiation job takes a model and creates the items described in the model by creating types, instances and mappings. A model can be instantiated many times.

SUBSCRIBE : devices/<clientId>/messages/devicebound/#

  • Agents should subscribe to a single wild card topic to receive all messages published to them.

  1. Agents that connect on port 443 with client certificate authentication must have Application Layer Protocol Negotiation (ALPN) TLS extension and use the ALPN protocol name listed in the ALPN protocols. 

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.


Last update: August 3, 2022