# MQTT Client Authentication

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).

## 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.

{% hint style="warning" %}
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.
{% endhint %}

### 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-3-0/documentation/security/tls-certificates/ca-certificates.md).
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](/2-3-0/documentation/security/tls-certificates/client-certificates.md) 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 |

{% 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-3-0/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-3-0/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.