# MQTT User Authentication

Connectware supports two authentication methods for MQTT clients: Username/password and x.509 certificate with Mutual TLS for CybusMQ connections. You can set the authentication method via the `CYBUS_BROKER_USE_MUTUAL_TLS` [environment variable](https://docs.cybus.io/2-0-2/documentation/environment-variables).

| Method            | Configuration                     | Client requirements                         |
| ----------------- | --------------------------------- | ------------------------------------------- |
| Username/Password | `CYBUS_BROKER_USE_MUTUAL_TLS=no`  | Client must provide username and password   |
| Mutual TLS        | `CYBUS_BROKER_USE_MUTUAL_TLS=yes` | Client must provide valid x.509 certificate |

## Username/Password Authentication

When Mutual TLS is disabled, MQTT clients authenticate using a username and password:

This authentication method works with all MQTT connection schemes (TCP, WebSocket, SSL/TLS).

## Mutual TLS Authentication

Mutual TLS offers enhanced security by eliminating password transmission and providing stronger client verification. When enabled, Mutual TLS provides certificate-based authentication:

* Requires a valid x.509 client certificate signed by the Connectware CA.
* The certificate's Common Name (CN) must match a Connectware username with grant type certificate.
* No username or password needed - possession of a valid certificate proves identity.

## MQTT Permissions

Once authenticated (by either method), MQTT clients can interact with topics based on their assigned permissions:

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

{% hint style="info" %}
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](https://docs.cybus.io/2-0-2/documentation/user-management/permissions).
{% endhint %}