# Access Control List

Access Control List (ACL) provides a more fine-grained approach to authorization. It defines rules that are matched from top to bottom. Once a rule is matched, its permission is applied, and the remaining rules are ignored.

## Configuration Items

| Name     | Type          | Required | Description                                 |
| -------- | ------------- | -------- | ------------------------------------------- |
| permit   | enum          | Yes      | permission: `allow` ,`deny`                 |
| action   | enum          | No       | operation: `publish`, `subscribe`, `pubsub` |
| topics   | Array[String] | No       | Array of Topic                              |
| username | String        | No       | Username: "`#`" means all users             |
| clientid | String        | No       | ClientID: "`#`" means all client IDs        |
| and      | Array[Object] | No       | `AND` operator                              |
| or       | Array[Object] | No       | `OR` operator                               |

## Configuration Example

This example demonstrates how to define access control rules for different users and topics, providing a flexible mechanism for managing MQTT permissions.

To enable access control, write your rules in the correct format in the `nanomq_acl.conf` file, and include this file in your main `nanomq.conf` configuration as described in the [Access Control Introduction](./introduction.md):

```
acl = {include "/etc/nanomq_acl.conf"}
```

### Sample ACL Configuration

```bash
rules = [
  # Allow MQTT client with username "dashboard" to subscribe to all system topics
  {"permit": "allow", "username": "dashboard", "action": "subscribe", "topics": ["$SYS/#"]},

  # Deny all users from subscribing to "$SYS/#" and "#" topics
  {"permit": "deny", "username": "#", "action": "subscribe", "topics": ["$SYS/#", "#"]},

  # Allow all other publish/subscribe operations
  {"permit": "allow"}
]
```

**Tips**

- The `@` symbol can be used to match specific topic patterns more precisely than standard wildcards. For example:

  ```bash
  {"permit": "deny", "username": "#", "action": "subscribe", "topics": ["$SYS/#", "@#", "@client/+/msg"]}
  ```

  This rule only denies subscription to the topics `#` and `client/+/msg`, but **does not** deny topics like `client/123/msg`, even though they match under MQTT wildcard rules. This allows finer-grained control.

- Dynamic placeholders `${clientid}` and `${username}` can be used within topic definitions to dynamically match client-specific values during authorization checks.

  Example:

  ```bash
  {"permit": "allow", "action": "publish", "topics": ["t/${clientid}"]}
  ```

  If a client with ID `nmq_c` attempts to publish to `t/nmq_c`, this rule will match exactly.