MQTT Client Authentication

Configure authentication for MQTT clients connecting to Connectware.

MQTT clients connecting to Connectware authenticate as Connectware users. Connectware supports two authentication methods for MQTT clients: username/password and X.509 certificate-based Mutual TLS (mTLS).

Method	Client requirements
Username/Password	Client must provide username and password
Mutual TLS	Client must provide valid X.509 certificate

Username/Password Authentication

MQTT clients can authenticate using a username and password. This authentication method works with all MQTT connection schemes (TCP, WebSocket, SSL/TLS).

LDAP Authentication for MQTT Clients

If LDAP is enabled, MQTT clients can authenticate with their LDAP credentials over username/password. On the first MQTT connection attempt, Connectware performs the LDAP lookup, creates the corresponding Connectware user, and assigns roles based on your LDAP configuration.

LDAP-based MQTT authentication works with MQTT 3.1, 3.1.1, and 5. If LDAP is unreachable or the credentials are invalid, Connectware denies the connection and logs the failure.

Successful authentications are cached and do not expire when LDAP roles or group memberships change. To force re-authentication, see Revoking Access After LDAP Changes (MQTT Clients Only).

For configuration details, see Single Sign-On with LDAP.

Mutual TLS Authentication

With mTLS, clients authenticate by presenting a valid X.509 certificate instead of a username and password. Connectware reads the certificate's Common Name (CN) as a username and matches it against a user configured with the certificate grant type. That user's roles and permissions govern which topics the client can access.

The client certificate must be signed by a Certificate Authority that Connectware trusts.

Each Connectware user can authenticate with either username/password or certificate-based authentication, not both. Configure the grant type per user in the Admin UI.

Setting Up Mutual TLS

To use mTLS, complete the following steps in Connectware:

1. Add your CA to the cybus_ca.crt certificate bundle so that Connectware can verify client certificates issued by your organization. See CA Certificates.

2. Enable certificate-based authentication for each user by setting the grant type to certificate in the user's settings in the Admin UI. See Client Certificates for the full setup procedure, including CSR generation and certificate signing.

MQTT Permissions

Once authenticated, MQTT clients can interact with topics based on the permissions assigned to their corresponding Connectware user:

Permission	Allowed actions
read	Subscribe to topics
write	Publish to topics
readWrite	Both subscribe and publish

To manage MQTT user permissions efficiently, create specific roles with appropriate topic permissions and assign them to users rather than configuring permissions individually. For more information, see Permissions.