Context
Change Type: Announcement
Product area: Platform services
Component: MQTT
Technical details
Build artifact: mqtt-service
Description
Caution
This change only affects the new Cumulocity MQTT Service capability.
The existing Cumulocity Core MQTT capability is not affected.
Introduction
To strengthen security and prevent client spoofing, the Cumulocity MQTT Service will soon require the ADMIN permission for the “Mqtt service” permission type for clients connecting via basic authentication.
Currently, basic authentication lacks a strict binding between the authenticated user and the MQTT clientId. This could allow a user with valid Cumulocity credentials to connect using any clientId and impersonate other devices. This change ensures that only explicitly authorized users and devices can use basic authentication to connect to the MQTT Service.
What is changing?
- Required role: A specific authorization role will be required for any user or device attempting to authenticate to the MQTT Service using basic authentication.
- No default assignment: To maintain a strict security posture, this role will not be added to any global roles by default.
- Message broker properties: The authentication type and username will now be passed as Pulsar message properties (
tx.clientUsername and tx.clientAuthType). This allows downstream consumers to validate the clientId against the authenticated username.
Clients connecting via certificate authentication are not affected by this change.
Impact on existing MQTT clients
This is a breaking change for clients utilizing basic authentication.
Once this change is deployed, any existing clients relying on basic authentication without the required explicit role will fail to connect. Administrators will need to manually assign the ADMIN permission for the “Mqtt service” permission type to the specific users or devices that legitimately require basic authentication access.
Roll-out plan
This change will take effect when the MQTT Service reaches General Availability (GA). Please update your user or device roles accordingly to ensure uninterrupted service.
Info
Because the Cumulocity MQTT Service is currently in Public Preview, it is not subject to the standard 6-month compatibility notice period defined in the Cumulocity Compatibility policy.
What is in detail meant with “ADMIN” permission? Will there be a new role introduced?
This does not impact microservices implementing the pulsar interface I guess?
Yes, there will be a new role type called “Mqtt service”, see the screen below:
It will affect MQTT clients using basic auth only, Pulsar interface stays as it is.
1 Like
Does that include device users? e.g. Would the “devices” group need to also have the new “Mqtt service” permissions in order to connect using basic auth credentials which are registered via the Bulk Device Registration API?
Yes, that affects all Cumulocity users, including device users. This is due to the generic nature of the MQTT Service; when working with it, clients can use any user account and are not limited to device users alone.
The role is not assigned to any group by default. Depending on the use case, it is up to the customer to decide if they would like to assign it “globally” to a device group, to a specific device user, or to any user account used to connect with the MQTT Service.
1 Like
When will we be able to test this change in eu-latest? There is currently no “Mqtt service” role type there. We have previously been informed that the MQTT Service would transition to GA at the end of March, which is… soon.
Hi Martin,
The new role was released in version 2026.73.0 which has been on eu-latest for a while now. It should reach cumulocity.com soon, too. If I look in my eu-latest tenant it is visible:
As mentioned in the announcement we have not assigned the new role to any of the global roles by default, as it grants access that might not be desired. Tenants should add the role to the global roles that make sense for their use case, which as discussed above could include the Device User role.
1 Like
Thanks. I can see the new role “Mqtt service” in eu-latest. From which date will this be explicitly required for basic auth clients on eu-latest, so that we can test it? Our use case is a microservice that receives LwM2M data from all devices forwarded through the MQTT service. The microservice is using service credentials to authenticate using basic auth with the appropriate roles given in the cumulocity.json manifest.
Hi Martin,
We expect to make this role explicitly required when the MQTT Service reaches General Availability (GA), which should tentatively be in the next week or so. However, that shouldn’t stop anyone from adding it to their required roles now to ensure a smooth transition.
That being said, we wanted to double-check if this change will actually affect you. Our understanding is that your microservice uses the Notifications 2.0 WebSockets interface.
If you are using this WebSocket implementation rather than the direct MQTT protocol, this new role requirement shouldn’t impact your current setup.
Thanks.
That is correct. The microservice is using a WebSocket to receive data from Notifications 2.0 using the “lwm2m” notification type. Please can you confirm that we do not need to add this new role to our microservice.
Yes, that is correct. If your microservice does not interface with the MQTT Service via the MQTT protocol using Basic authentication, this change will not affect you.
1 Like
