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:
- Tenant uploads a CA certificate that can be used to validate the certificates used by devices/agents (MQTT clients) of this tenant.
- 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.
- 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 Client JWT Requirements¶
Required Headers¶
alg
: RS256 algorithm is mandatory.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.)
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). The token 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", //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.
- Version must be 3 (indicating X.509 v3)
- Key Usage field and digitalSignature extension is required.
- Subject DN must be unique per tenant (for example, CN=Volkan Sen, OU=CT, o=Siemens, L=Istanbul, C=TR)
- Authority Key Identifier extension is required.
- Issuer DN is required.
Highly Recommended Requirements¶
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.
- Validity of the certificate should be valid up to one year. The current date and time should be between
notBefore
andnotAfter
. - 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¶
- Message Size: Maximum size of an MQTT message cannot exceed 24 KB.
- Message Frequency: Clients should not send messages with higher frequency than 1 message per 5 seconds.
- MQTT CONNECT Username: Clients must use
_CertificateBearer
as username within MQTT Connect message. - MQTT CONNECT Password: Refer to X509 Client JWT Requirements.
-
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. -
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(~)
-
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."
- Name :
- Agent created with following values:
- Agent Id:
<AssetId>
- Name :
<clientId>
- Security Profile: "CACertifiedX509"
- Agent Id:
- 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:
-
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.
-
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.
-
Asset/Agent/Type Quota exceeded.
Please check your asset, type and agent consumption via Asset Manager in the Launchpad and upgrade if necessary.
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.
Except where otherwise noted, content on this site is licensed under the Development License Agreement.