Onboarding MindConnect MQTT Agent¶

Overview¶

MindConnect MQTT agents can be onboarded to Insights Hub using agent certificates that are issued by the owner tenant's CA certificate.

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

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

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

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

Where <tenant> is the tenant name and <AgentCertificate.Subject.CommonName> is Common Name attribute of agent certificate subject. A single client id represents a single agent, and multiple connections using a single client id are not allowed.

Prerequisites¶

To generate certificates, ensure to have the OpenSSLtoolkit or an equivalent setup to create certificates.
MQTTX is installed on your computer or an equivalent setup.
Certificates used by agents must be signed by uploaded CA certificates. Steps in the documents Managing CA Certificates using UI / Managing CA Certificates using MindConnect MQTT API must be completed before agent onboarding:

Agent Onboarding¶

EU1¶

Create an agent private key

Following commands creates an agent private key (line 1); creates a CSR using the agent name as certificate subject's Common Name, that is valid for 1 year (line 2). Next, the tenant's private key is used to issue the agent certificate using created CSR (line 3). Finally, the agent certificate and CA certificate are concatenated to use in later steps.

LINUX:
```
export TENANT=<yourtenant>
export DEVICE_NAME=<yourdevicename>
export COUNTRY_CODE =<COUNTRY_CODE>
export CITY =<CITY>
export ORGANIZATION =<ORGANIZATION>
```
1. openssl genrsa -out $DEVICE_NAME.key 2048
2. openssl req -new -key $DEVICE_NAME.key -out $DEVICE_NAME.csr -subj "/C=$COUNTRY_CODE/ST=$CITY/O=$ORGANIZATION/OU=IT/CN=$DEVICE_NAME"
3. openssl x509 -req -in $DEVICE_NAME.csr -CA "$TENANT.pem" -CAkey "$TENANT.key" -CAcreateserial -out $DEVICE_NAME.pem -days 365 -sha256
4. cat $DEVICE_NAME.pem "$TENANT.pem" > "$DEVICE_NAME"_chain.pem
You can view the created certificate with the following command:

openssl x509 -in "$DEVICE_NAME"_chain.pem -text -noout

WINDOWS:
```
set TENANT=<yourtenant>
set DEVICE_NAME=<yourdevicename>
set COUNTRY_CODE =<COUNTRY_CODE>
set CITY =<CITY>
set ORGANIZATION =<ORGANIZATION>
```
1. openssl genrsa -out %DEVICE_NAME%.key 2048
2. openssl req -new -key %DEVICE_NAME%.key -out %DEVICE_NAME%.csr -subj "/C=%COUNTRY_CODE%/ST=%CITY%/O=%ORGANIZATION%/OU=IT/CN=%DEVICE_NAME%"
3. openssl x509 -req -in %DEVICE_NAME%.csr -CA "%TENANT%.pem" -CAkey "%TENANT%.key" -CAcreateserial -out %DEVICE_NAME%.pem -days 365 -sha256
4. type %DEVICE_NAME%.pem "%TENANT%.pem" > "%DEVICE_NAME%"_chain.pem
You can view the created certificate with the following command:

openssl x509 -in "%DEVICE_NAME%"_chain.pem -text -noout
Connecting to MindConnect MQTT broker

Login to your Insights Hub environment and go to the "Asset Manager" application, in "Connectivity" section, select "Manage MQTT Certificates" and click "Broker Information". Under this, "MindConnect MQTT Broker Url" and "MindConnect MQTT Broker Certificate" can be found.

Connection parameters are as follows:

ClientId: <tenant>_<AgentCertificate.Subject.CommonName>

Username: <empty>

Password: <empty>

Client Certificate: <DEVICE_NAME>_chain.pem

Client Key: <DEVICE_NAME>.key

At the first connection attempt, the broker will close the connection and start provisioning of the agent in the backend. Once completed, you can see your newly created agent asset in the Asset Manager application in the Launchpad.

After a couple of seconds, retry the connection attempt. This time connection will remain intact since provisioning is complete.
- Mosquitto Connection Example
For example, the following mosquitto_sub command will connect and subscribe to a topic (You need AmazonRootCA1.pem to contain broker certificate, see above for how to find it):
```
mosquitto_sub --cafile AmazonRootCA1.pem --key "$DEVICE_NAME".key \ --cert "$DEVICE_NAME".pem -h "$MqttBrokerHost" \ -p 8883 -t tc/"$TENANT"/"$CLIENT_ID"/i/amo_v3/ms -i $CLIENT_ID -v -d
```
- MQTTX Connection Example
Once connected, clients can utilize the topics defined by applications available on MDSP AWS MindConnect Connectivity. Inspect async API specs of related services to learn about available topics and payload schemas.

EU2¶

Create an agent private key

Following commands creates an agent private key (line 1); creates a CSR using the clientId as certificate subject's Common Name, that is valid for 1 year (line 2). Next, the tenant's private key is used to issue the agent certificate using created CSR (line 3). Finally, the client certificate and CA certificate are concatenated to use in later steps.

LINUX:
```
export TENANT=<yourtenant>
export DEVICE_NAME=<yourdevicename>
export COUNTRY_CODE =<COUNTRY_CODE>
export CITY =<CITY>
export ORGANIZATION =<ORGANIZATION>
export CLIENT_ID="$TENANT"_"$DEVICE_NAME"
```
1. openssl genrsa -out $DEVICE_NAME.key 2048
2. openssl req -new -key $DEVICE_NAME.key -out $DEVICE_NAME.csr -subj "/C=$COUNTRY_CODE/ST=$CITY/O=$ORGANIZATION/OU=IT/CN=$CLIENT_ID"
3. openssl x509 -req -in $DEVICE_NAME.csr -CA "$TENANT.pem" -CAkey "$TENANT.key" -CAcreateserial -out $DEVICE_NAME.pem -days 365 -sha256
4. cat $DEVICE_NAME.pem "$TENANT.pem" > "$DEVICE_NAME"_chain.pem
You can view the created certificate with the following command:

openssl x509 -in "$DEVICE_NAME"_chain.pem -text -noout

WINDOWS:
```
set TENANT=<yourtenant>
set DEVICE_NAME=<yourdevicename>
set COUNTRY_CODE =<COUNTRY_CODE>
set CITY =<CITY>
set ORGANIZATION =<ORGANIZATION>
set CLIENT_ID="%TENANT%"_"%DEVICE_NAME%"
```
1. openssl genrsa -out %DEVICE_NAME%.key 2048
2. openssl req -new -key %DEVICE_NAME%.key -out %DEVICE_NAME%.csr -subj "/C=%COUNTRY_CODE%/ST=%CITY%/O=%ORGANIZATION%/OU=IT/CN=%CLIENT_ID%"
3. openssl x509 -req -in %DEVICE_NAME%.csr -CA "%TENANT%.pem" -CAkey "%TENANT%.key" -CAcreateserial -out %DEVICE_NAME%.pem -days 365 -sha256
4. type %DEVICE_NAME%.pem "%TENANT%.pem" > "%DEVICE_NAME%"_chain.pem
You can view the created certificate with the following command:

openssl x509 -in "%DEVICE_NAME%"_chain.pem -text -noout
Connecting to a global DPS (Device Provisioning Service)

Before connecting to the MQTT broker, each device needs to connect to a global DPS (Device Provisioning Service) provided by Azure to register itself and get further MQTT broker parameters.

For further information about Device Provisioning Service, refer to IoT Hub Device Provisioning Service

Agents need to connect to the DPS endpoint using TLS with mutual authentication. To accomplish this, the agent needs to:

Login to your Insights Hub environment and go to the "Asset Manager" application, in the "Connectivity" section, select "Manage MQTT Certificates" and click "Broker Information". Under this, "MindConnect MQTT Broker Url" and "MindConnect MQTT Broker Certificate" can be found.

Login to your Insights Hub environment and go to the "Asset Manager" application, in the "Connectivity" section, select "Manage MQTT Certificates" and click "Own Certificates". Under this, ScopeId can be found.

Connection parameters are as follows:

Agent Certificate Chain: "$CLIENT_ID"_chain.pem

Agent Private Key: "$CLIENT_ID".key

After a successful TLS connection, the agent must send an MQTT CONNECT message with proper username, empty password, and proper client id described as below:

Username = <scopeId>/registrations/<clientId>/api-version=2019-03-31

Password = <empty>

ClientId = <tenant>_<uniqueId>: must match agent certificate subject's Common Name attribute
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 Insights Hub. A response object will be published by the DPS to the topic subscribed in the first step. It looks like this:
```
{
"operationId": "4.abe16cbf3f71fe17.19a42d8c-76f4-438c-be83-85d01f7bff73",
"status": "assigning"
}
```
Ensure that the status is 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. Example:
```
{
"operationId": "4.abe16cbf3f71fe17.19a42d8c-76f4-438c-be83-85d01f7bff73",
"status": "assigned",
"registrationState": {
    "x509": {
    "enrollmentGroupId": "TenantEnrollmentGroup-TenantCACertificate-<tenantId>"
    },
    "registrationId": "<tenantId>_MqttTestAgent",
    "createdDateTimeUtc": "2021-06-03T08:37:58.8521797Z",
    "assignedHub": "conn-prod-ex-iothub.azure-devices.net",
    "deviceId": "<tenantId>_MqttTestAgent",
    "status": "assigned",
    "substatus": "initialAssignment",
    "lastUpdatedDateTimeUtc": "2021-06-03T08:37:59.1384561Z",
    "etag": ""
}
}
```
Now status is assigned. The registarationState.assignedHub attribute indicates the IoT-Hub URI that the registered agent should connect to.
Connecting to MQTT broker

Industrial IoT Services (e.g. MindConnect, AssetModeler, etc.) are accessible to agents on the MQTT broker address given in the registration process by DPS. Agents should connect to that broker to access MDSP services.

Connection parameters are as follows:

MQTT broker host (iothubhostname): <Address of assignedHub, as reported by DPS>

MQTT broker port: 8883

MQTT broker certificate: Azure IoT Hub uses certificates issued by Baltimore CyberTrust Root. See IoT Hub TLS certificate update for details.

ClientId: <tenant>_<uniqueId> // Same as DPS registration

Username: <iothubhostname>/<client_id>/?api-version=2018-06-30

Password: <empty>// Same as DPS registration

Once connected, clients can utilize the topics defined by applications available on MDSP Azure MindConnect Connectivity.
MQTTX Agent Onboarding Example
- Connect to DPS Server
- 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 Insights Hub. A response object will be published by the DPS to the topic subscribed in the first step. It looks like this:
- 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.
  
  MindConnect MQTT Broker Url is assignedHub's value in the response message.
- Connect MQTT Broker
  
  Azure IoT Hub uses certificates issued by Baltimore CyberTrust Root.
  
  Login to your Insights Hub environment and go to the "Asset Manager" application, in the "Connectivity section", select "Manage MQTT Certificates" and click "Broker Information". Under this, "MindConnect MQTT Broker Url" and "MindConnect MQTT Broker Certificate" can be found.
  
  MQTT broker host: <Address of assignedHub, as reported by DPS>
  
  MQTT broker port: 8883
  
  ClientId: <tenant>_<uniqueId> // Same as DPS registration
  
  Username: <assignedHub>/<client_id>/?api-version=2018-06-30
  
  Password: <empty>// Same as DPS registration

Private Cloud¶

MindConnect MQTT is just available for Rancher environments.

Create an agent private key

Following commands creates an agent private key (line 1); creates a CSR using the clientId as certificate subject's Common Name, that is valid for 1 year (line 2). Next, the tenant's private key is used to issue the agent certificate using created CSR (line 3). Finally, the client certificate and CA certificate are concatenated to use in later steps.

**LINUX:**

```cmd
export TENANT=<yourtenant>
export DEVICE_NAME=<yourdevicename>
export COUNTRY_CODE =<COUNTRY_CODE>
export CITY =<CITY>
export ORGANIZATION =<ORGANIZATION>
export CLIENT_ID="$TENANT"_"$DEVICE_NAME"
```

openssl genrsa -out $DEVICE_NAME.key 2048
openssl req -new -key $DEVICE_NAME.key -out $DEVICE_NAME.csr -subj "/C=$COUNTRY_CODE/ST=$CITY/O=$ORGANIZATION/OU=IT/CN=$DEVICE_NAME"
openssl x509 -req -in $DEVICE_NAME.csr -CA "$TENANT.pem" -CAkey "$TENANT.key" -CAcreateserial -out $DEVICE_NAME.pem -days 365 -sha256
cat $DEVICE_NAME.pem "$TENANT.pem" > "$DEVICE_NAME"_chain.pem

You can view the created certificate with the following command:

openssl x509 -in "$DEVICE_NAME"_chain.pem -text -noout

**WINDOWS:**

```cmd
set TENANT=<yourtenant>
set DEVICE_NAME=<yourdevicename>
set COUNTRY_CODE =<COUNTRY_CODE>
set CITY =<CITY>
set ORGANIZATION =<ORGANIZATION>
set CLIENT_ID="%TENANT%"_"%DEVICE_NAME%"
```

openssl genrsa -out %DEVICE_NAME%.key 2048
openssl req -new -key %DEVICE_NAME%.key -out %DEVICE_NAME%.csr -subj "/C=%COUNTRY_CODE%/ST=%CITY%/O=%ORGANIZATION%/OU=IT/CN=%DEVICE_NAME%"
openssl x509 -req -in %DEVICE_NAME%.csr -CA "%TENANT%.pem" -CAkey "%TENANT%.key" -CAcreateserial -out %DEVICE_NAME%.pem -days 365 -sha256
type %DEVICE_NAME%.pem "%TENANT%.pem" > "%DEVICE_NAME%"_chain.pem

You can view the created certificate with the following command:

openssl x509 -in "%DEVICE_NAME%"_chain.pem -text -noout 2. Create X509 Client JWT

Required Headers

alg: value must be “RS256”

x5c: Value of that claim must satisfy the following conditions:

- Contains Device Certificate and TenantCA Certificate sequentially

- Certificates must be in order (eg: [Device Certificate, TenantCA Certificate])

- All certificates must be valid (Please see Device Certificate Requirements & TenantCA and Intermediate Certificate Requirements for details below.)

typ: value must be “JWT”
Required and Optional Claims

jti: Unique identifier for the token. The format is String in UUID with a maximum of 36 characters.

iss: Issuer information of the token. The value must be MQTT Client id.

sub: Subject information of the token. The value must be MQTT Client id (same as iss).

aud: Audience claim identifies the recipients that the token is intended for. Value must be [“MQTTBroker”]

iat: Time at which the token was issued. Format is epoch time in seconds (the number of seconds from 1970-01-01T00:00:00Z UTC).

*nbf: Identifies the time before which the token must not be accepted for processing. Format is epoch time in seconds (the number of seconds from 1970-01-01T00:00:00Z UTC). It is optional claim, if the token has that claim Insights Hub checks the notBefore time and validates the token.

exp: Expiration time of the token. The format is epoch time in seconds (the number of seconds from 1970-01-01T00:00:00Z UTC). Thetoken must be valid up to one hour. Therefore, the difference between iat and exp must be maximum one hour.

schemas: Defines the semantics of custom claims of the token. The value must be [“urn:siemens:mindsphere:v1”].

ten: Any string value with a maximum of 36 characters.

*: denotes optional claim.

Signature JWT must be signed by the Device Certificate private key. For example, the JWT used by the device follows the structure as below:

    {
    "alg":"RS256", 
    "x5c": ["MIICYzCCAcygAwIBAgIBADANB...","MIIDCTCCAfGgAwIBAgIUU..."],
    "typ":"JWT"
    }

Creation Example

Open jwt.io On jwt io there are two sections. Encoded and Decoded. We will use Decoded section to create JWT.

Header should be like following example.

    {
    "alg":"RS256",
    "x5c": ["MIICYzCCAcygAwIBAgIBADANB...","MIIDCTCCAfGgAwIBAgIUU..."],
    "typ":"JWT"
    }

Payload should be like following example.

    {
        "jti": "anyId",
        "iss": "<yourclientid>",
        "sub": "<yourclientid>",
        "aud": ["MQTTBroker"],
        "iat": <currentepochdate>,
        "exp": <onehouraftercurrentepochdate>,
        "schemas": ["urn:siemens:mindsphere:v1"],
        "ten": "<tenant>"
        }

You need to add your device private key. You can find in <yourdevicename>.key file.

MQTTX Agent Onboarding Example

Connection parameters are as follows:

ClientId: <tenant>_<AgentCertificate.Subject.CommonName> Host: Customer specific MQTT broker URL. It should be started with “mindconnectmqtt” CA File: Customer specific MQTT Root CA. Username: _CertificateBearer Password: Created X509 Client JWT in above section.

At the first connection attempt, the broker will close the connection and start provisioning of the agent in the Insights Hub backend. Once completed, you can see your newly created agent asset in the Asset Manager application in the Launchpad.

After a couple of seconds, retry the connection attempt. This time connection will remain intact since provisioning is complete.

Once connected, clients can utilize the topics defined by applications available on MDSP AWS MindConnect Connectivity. Inspect async API specs of related services to learn about available topics and payload schemas.

Last update: October 12, 2023

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