Skip to content

Connecting to OPC UA PubSub Service via MQTT

As part of the ongoing development and support strategy, the usage of MQTT for connecting to the OPC PUB SUB agent is being phased out. To ensure continued compatibility and reliability, It is recommended to opt Connecting to OPC UA Pub Sub agents via MindConnect MQTT broker option for the connectivity requirements.

Basics

CA Certificate

All MQTT-based devices connecting with Insights Hub needs to be authenticated by a unique certificate identity.

Note

MindConnect MQTT is not applicable for Virtual Private Cloud (VPC).

Registration Code

The user needs to get the registration code to use it as the common name of the verification certificate.

Verification Certificate

To ensure the certificate uploader also possesses the corresponding private key, the user needs to prove by issuing a verification certificate with the common name provided by Insights Hub using the private key.

Security Concept - Onboarding CertificateBearer

This feature allows the tenant admins to upload a certification authority (CA) certificate for their tenant. Later, the clients get authenticated and Connecting to OPC UA PubSub Service via MQTT auto-onboarded if they approach with a certificate issued by CA cert or CA cert issued intermediaries.

To enable successful device authentication based on a JWT, perform the following steps:

  1. Tenant uploads a CA certificate that can be used to validate the certificates used by devices/agents (MQTT clients) of this tenant.
  2. The device connects to MQTT service and uses a self-signed JWT, signed by the private counterpart of public key residing in device certificate, which is issued by the CA certificate.
  3. The broker validates the JWT to confirm that the JWT is valid and the device certificate was issued by a valid tenant CA.

X509 CA Authentication

X509 CA Authentication

X509 Client JWT Requirements

Required Headers

  1. alg: RS256 algorithm is mandatory.
  2. x5c: Value of that claim must satisfy the following conditions:
    • Contains Device Certificate as first certificate in chain
    • Contains TenantCA Certificate
    • Contains maximum 3 certificates
    • Certificates must be in order (eg: [Device Certificate, Device Certificate Issuer, ..])
    • All certificates in the chain must be valid (Please see Device Certificate Requirements & TenantCA and Intermediate Certificate Requirements for details below.)
  3. typ: value must be "JWT".

Required and Optional Claims

  1. jti: Unique identifier for the token. The format is String in UUID with a maximum of 36 characters.
  2. iss: Issuer information of the token. The value must be MQTT Client id.
  3. sub: Subject information of the token. The value must be MQTT Client id (same as iss).
  4. aud: Audience claim identifies the recipients that the token is intended for. Value must be [“MQTTBroker”]
  5. 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).
  6. *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.
  7. exp: Expiration time of the token. The format is epoch time in seconds (the number of seconds from 1970-01-01T00:00:00Z UTC). The token must be valid up to one hour. Therefore, the difference between iat and exp must be maximum one hour.
  8. schemas: Defines the semantics of custom claims of the token. The value must be ["urn:siemens:mindsphere:v1"].
  9. 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", //algorithm used for the signature - must be RS256
    "x5c": ["MIICYzCCAcygAwIBAgIBADANB..."] //X.509 Certificate Chain
    "typ":"JWT"
}
.
{
    "jti":"cee313f5-dca3-44e5-8dbe-8fd9354e847a" // unique identifier for the token
    "iss":"049fa224-c2c8-49cf-964c-2b4a0fd2b0a0", //id of the agent MQTT.clientId (for _CertificateBearer case) - REQUIRED
    "sub":"049fa224-c2c8-49cf-964c-2b4a0fd2b0a0", //id of the agent MQTT.clientId (for _CertificateBearer case) - REQUIRED
    "aud": ["MQTTBroker"], //audience identifier of the MindSphere authorization server - REQUIRED
    "iat":1513947904, //time when the token was issued - REQUIRED
    "nbf":1513947904, //time when the token was issued - OPTIONAL
    "exp":1513951504, //time until the token is valid - REQUIRED
    "schemas": ["urn:siemens:mindsphere:v1"], //schema used to define the semantics of custom claims - REQUIRED
    "ten":"" //tenant ID 
}
.
[... signature with private key of agent 049fa224-c2c8-49cf-964c-2b4a0fd2b0a0 ...]

Certificate Requirements

Device Certificate Requirements

Mandatory Requirements

While uploading Device Certificates with CONNECT request, the following requirements are checked. In case of any violations, CONNECT request is denied.

  1. Version must be 3 (indicating X.509 v3)
  2. Key Usage field and digitalSignature extension is required.
  3. Subject DN must be unique per tenant (for example, CN=Volkan Sen, OU=CT, o=Siemens, L=Istanbul, C=TR)
  4. Authority Key Identifier extension is required.
  5. Issuer DN is required.

The entire responsibility for quality of Devices Certificates belongs to the end-users.

However, the following quality items are recommended to the end-users for their certificates.

  1. Validity of the certificate should be valid up to one year. The current date and time should be between notBefore and notAfter.
  2. Device certificates' signing algorithm should be SHA2.

Not Supported functionalities

The certificate's revocation status not supported. This functionality is not supported currently. To handle revocations of the certificates, the end-user should remove TenantCA Certificate from the Certificate Manager. Thus, Device Certificate and Certification Path cannot be validated by Insights Hub.

MQTT Broker Limits and Constraints

Deviation from MQTT Spec 3.1.1

  • QoS2 messages are not supported.
  • Clients' session data is stored in broker if they connect with CleanSession=false. If such a client is disconnected, the messages sent to its subscribed topics are retained in broker for 24 hours.
  • Retain, LastWillAndTestament are not supported.

Limitations

  1. Message Size: Maximum size of an MQTT message cannot exceed 24 KB.
  2. Message Frequency: Clients should not send messages with higher frequency than 1 message per 5 seconds.
  3. MQTT CONNECT Username: Clients must use _CertificateBearer as username within MQTT Connect message.
  4. MQTT CONNECT Password: Refer to X509 Client JWT Requirements.

  5. MQTT CONNECT Client Id: Client id cannot exceed 128 chars and should not be shorter than 16 chars. Client id is provided by clients without prior knowledge to broker. The clients needs to provide globally unique client identifiers.
    Once a client is connected with a certain client id, the client id is reserved to that client (Id is bound to certificate subject and tenant name). No other client can connect with this client id. This binding persists until an agent is deleted. If the client id provided is already reserved for another agent on the system, the client will get an CONNACK package with 0x04 return code. In such a scenario, the client needs to retry with a different client id.

  6. Topic names: For OPC UA PubSub API V3 following topics are supported:

        c/<clientId>/o/opcua/v3/u/d/t
    c/<clientId>/o/opcua/v3/u/m/t
    c/<clientId>/o/opcua/v3/u/d/e
    c/<clientId>/o/opcua/v3/u/m/e

    The following character groups are allowed to be used for topics:

    • Alphabetic (a-zA-Z)
    • Numeric 0-9
    • Additional characters: Underscore (_), hyphen (-) and tilde(~)

  7. Auto-Provisioning: Once an agent successfully connects to MQTT broker with Tenant CA issued certificate for the first time, the following actions take place:

    • The submitted client id is reserved for the agent. That means, neither another client can assume that id, nor the agent can assume some other id.
    • A new agent asset in Asset Management and a new agent entity in Agent Management is created.
    • Asset created with following values:
      • Name : <clientId>
      • Asset Type: core.mcX509
      • Description: "Asset for agent provisioned automatically with X.509 certificates."
    • Agent created with following values:
      • Agent Id: <AssetId>
      • Name : <clientId>
      • Security Profile: "CACertifiedX509"
    • Newly created agent's onboarding status is set to ONBOARDED from NOT_ONBOARDED state.
    • The number of agents allowed to be auto-provisioned per tenant is 50.

MQTT Broker - Common Connection Errors

When connecting to the MQTT Broker RabbitMQ only one error message is returned to the publishers: "BadUserNameOrPassword". The reason behind the error might be as follows:

  1. The JWT is invalid.

    The most common causes for an invalid JTW are:

    • Certificate path validation failed because of CertificateExpiredException.
    • The JWT is not yet valid as the evaluation time is before the not before claim time (nbf). Please see the JWT requirements under X509 Client JWT Requirements.

  2. Root Certificate is missing.

    Please check if the Tenant Certificate is uploaded via Settings/Certificate Manager in the Launchpad.

    You can also find the device certificate requirements under Certificate Requirements.

  3. Asset/Agent/Type Quota exceeded.

    Please check your asset, type and agent consumption via Asset Manager in the Launchpad and upgrade if necessary.

    AssetQuota

X509 Agent Access Token

The Agents connected to MQTT Broker can get the agent access token via access token endpoint(/oauth/token) of AgentManagement service. For more information, refer Agent Management Service.

Last update: December 13, 2023

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