# 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](/2-0-2/documentation/environment-variables.md).

| 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](/2-0-2/documentation/user-management/permissions.md).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cybus.io/2-0-2/documentation/user-management/mqtt-user-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.