Skip to content

update(mnesia): Add client ID/username regex #3117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: release-5.9
Choose a base branch
from
Open

update(mnesia): Add client ID/username regex #3117

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
991ece0
update(mnesia): Add client ID/username regex
Meggielqk Aug 11, 2025
d3fdc8e
Update getting-started.md
Meggielqk Aug 28, 2025
040ff33
Update REST API part
Meggielqk Sep 28, 2025
bcf603b
Remove "open-source" note
Meggielqk Sep 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 135 additions & 45 deletions en_US/access-control/authz/mnesia.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Knowledge about [basic EMQX authorization concepts](./authz.md)

:::

## Configure with Dashboard
## Create Built-in Database Authorizer via Dashboard

1. On the [EMQX Dashboard](http://127.0.0.1:18083/#/authentication), navigate to **Access Control** > **Authorization** in the left-hand menu to open the **Authorization** page.

Expand All @@ -26,7 +26,7 @@ Knowledge about [basic EMQX authorization concepts](./authz.md)

4. Click **Create** to complete the setup.

## Configure with Configuration File
## Create Built-in Database Authorizer via Configuration File

The built-in database authorizer is identified by type `built_in_database`.

Expand All @@ -51,71 +51,161 @@ You can create authorization rules through the Dashboard or API.

### Create Authorization Rules via Dashboard

On the **Authorization** page in Dashboard, click the **Permissions** button in the **Actions** column of the **Built-in Database** backend.
You can define authorization rules directly from the EMQX Dashboard by using the **Permissions** page of the **Built-in Database** backend.

#### Access the Permissions Page

1. In the Dashboard, go to the **Authorization** page.
2. In the **Actions** column of the **Built-in Database** backend, click **Permissions**.

![authz-mnesia-rule](./assets/authz-mnesia-rule.png)

You can set authorization checks based on the client ID, username, or topic as needed.
#### Authorization Rule Scope

Authorization rules can be configured at three scopes:

- **Client ID**: Apply rules to a specific client ID.
- **Username**: Apply rules to a specific username.
- **All Users**: Apply rules to all clients/users, optionally filtered by patterns or IP ranges.

#### Common Rule Fields

These fields are available for all rule types:

| Field | Description |
| -------------------- | ------------------------------------------------------------ |
| **Action** | The operation type the rule applies to. Options: `Publish`, `Subscribe`, `Publish & Subscribe`. |
| **Permission** | Whether to allow or deny the operation. Options: `Allow`, `Deny`. |
| **Topic** | The MQTT topic this rule applies to. Wildcards (`+`, `#`) are supported. |
| **QoS** | Allowed QoS levels. Multiple values can be selected: `0`, `1`, `2`. |
| **Retain** | Whether the rule applies to retained messages. Options: `true`, `false`, `All`. |
| **IP Address Range** | Specifies the client IP range this rule applies to. Supports CIDR notation (e.g., `192.168.1.0/24`) or exact IPs. |
| **Listener** | The listener this rule applies to. Use `{type}:{name}` format, e.g., `tcp:default`, `ws:default`. |
| **Zone** | The Zone in which the rule takes effect. Applicable in multi-Zone deployments. |

#### Fields by Rule Scope

| Rule Scope | Fields |
| ------------- | ------------------------------------------------------------ |
| **Client ID** | **Client ID**: (Required) Exact client ID to which this rule applies.<br />**Username Pattern**: (Optional) A regular expression to match usernames for which this rule is valid. |
| **Username** | **Username**: (Required) Exact username to which this rule applies.<br />**Client ID Pattern**: (Optional) A regular expression to match client IDs for which this rule is valid. |
| **All Users** | **Client ID Pattern**: (Optional) A regular expression to match usernames for which this rule is valid.<br />**Username Pattern**: (Optional) A regular expression to match usernames for which this rule is valid. |

**Example patterns:**

- `^device-user-.*`: Matches usernames starting with `device-user-`.
- `^sensor-.*`: Matches client IDs starting with `sensor-`.

#### Add a Rule

1. On the **Permissions** page, select the target tab: **Client ID**, **Username**, or **All Users**.
2. Click **Add**.
3. Fill in the [common fields](#common-rule-fields) and any [scope-specific fields](#fields-by-rule-scope).
4. (Optional) Click **Add Permission** to add multiple rules. Use the **Up** and **Down** buttons to adjust rule execution order.
5. Click **Add** to save the rule.

#### Manage Multiple Rules (All Users Only)

For **All Users** rules, you can change rule order from the **More** menu in the **Actions** column:

- Move Up
- Move Down
- Move to Top
- Move to Bottom

- **Client ID**: See the **Client ID** tab, specify the client that this rule applies to.
- **Username**: See the **Username** tab, specify the user that this rule applies to.
- **Permission**: Whether to allow or deny a certain type of operation request from the current client/user; optional values: **Allow**, **Deny**.
- **Action**: Configure the operation corresponding to this rule; optional values: **Publish**, **Subscribe**, **Publish & Subscribe**.
- **Topic**: Configure the topic corresponding to this rule.
Rules are evaluated from top to bottom, so order determines priority.

EMQX supports configuring multiple authorization check rules for a single client or user, and you can adjust the execution order and priority of different rules through the **Move Up** and **Move Down** buttons on the page.
#### Edit and Manage Rules

If you want to configure authorization check rules for multiple clients or users at the same time, you can import the relevant configuration through the HTTP API.
On the **Permissions** page, you can edit or delete existing rules:

### Create via REST API
- In the **Actions** column of the corresponding rule, click the **Edit** button to modify rule fields, matching patterns, or IP range settings.
- Click the **Delete** button to remove a rule.

Rules are also managed through `/api/v5/authorization/sources/built_in_database` APIs.
### Create Authorization Rules via REST API
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This part seems to be mostly outdated...
The endpoints are

        "/authorization/sources/built_in_database/rules/users",
        "/authorization/sources/built_in_database/rules/clients",
        "/authorization/sources/built_in_database/rules/users/:username",
        "/authorization/sources/built_in_database/rules/clients/:clientid",
        "/authorization/sources/built_in_database/rules/all"

Also the API directly reflects the dashboard, there are three scopes: username, clientid and all.

To create rules, e.g. for a user, the request is the following:

curl 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/users' \
- X POST \
...[headers]... \
  --data-raw '[{"username":"sdfs","rules":[{"topic":"sdfv","permission":"allow","action":"publish","qos":[0,1,2],"retain":"all"}]}]'

To update rules e.g. for a user:

curl 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/users/sdfs' \
  -X 'PUT' \
... [headers]... \
  --data-raw '{"username":"sdfs","rules":[{"action":"publish","retain":"all","topic":"sdfvsdf","qos":[0,1,2],"permission":"allow"}]}'

For /authorization/sources/built_in_database/rules/all endpoint there is no PUT request, just POST updating/creating all the rules.

There is no such hing as scope & scope_value 🤔

Also see swagger doc on a running release-60 instance: http://localhost:18083/api-docs/index.html#/Authorization/put_authorization_sources_built_in_database_rules_users__username_


Each rule is applied to:
* a particular client identified by clientid
* `/api/v5/authorization/sources/built_in_database/clientid`
* a particular client identified by username
* `/api/v5/authorization/sources/built_in_database/username`
You can also manage authorization rules through the REST API. The API endpoints correspond directly to the Dashboard’s three scopes: Username, Client ID, and All Users.

* all clients
* `/api/v5/authorization/sources/built_in_database/all`
#### Endpoints

- **Username rules**
- `POST /authorization/sources/built_in_database/rules/users`: Create rules for a user.
- `PUT /authorization/sources/built_in_database/rules/users/:username`: Replace rules for a specific user.
- **Client ID rules**
- `POST /authorization/sources/built_in_database/rules/clients`: Create rules for a client.
- `PUT /authorization/sources/built_in_database/rules/clients/:clientid`: Replace rules for a specific client.
- **All Users rules**
- `POST /authorization/sources/built_in_database/rules/all`: Create or replace global rules that apply to all clients/users.
- There is no `PUT` request, just `POST` updating or creating all the rules.

Below is a quick example of how to create rules for a client (`client1`):
#### Example: Create Rules for a User

```bash
curl -X 'POST' \
'http://localhost:18083/api/v5/authorization/sources/built_in_database/clientid' \
-H 'accept: */*' \
curl -X POST 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/users' \
-H 'Content-Type: application/json' \
-d '[
{
"clientid": "client1",
{
"username": "user1",
"rules": [
{
"topic": "v1/devices/#",
"permission": "allow",
"action": "publish",
"qos": [0,1,2],
"retain": "all"
}
]
}
]'
```

#### Example: Update Rules for a User

```bash
curl -X PUT 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/users/user1' \
-H 'Content-Type: application/json' \
-d '{
"username": "user1",
"rules": [
{
"action": "publish",
"topic": "v1/devices/+/state",
"permission": "allow",
"topic": "test/topic/1"
},
{
"action": "subscribe",
"permission": "allow",
"topic": "test/topic/2"
},
{
"action": "all",
"permission": "deny",
"topic": "eq test/#"
"qos": [0,1],
"retain": "all"
}
]
}
]'
}'
```

Each rule contains:
* `permission`: Whether to allow or deny a certain type of operation request from current client/user; optional values: `allow` or `deny`;
* `action`: Configure the operation corresponding to this rule; optional values: `publish`, `subscribe`, or `all`;
* `topic`: Configure the corresponding to this rule, supporting [topic placeholders](./authz.md#topic-placeholders).
* `qos`: (Optional) A number array used to specify the QoS levels that the rule applies to, e.g. `[0, 1]`, `[1, 2]`. The default is all QoS levels.
* `retain`: (Optional) Used to specify whether the current rule supports retained messages. Value options are `true`, `false`. Default is to allow retained messages.
#### Example: Create Rules for All Users

```bash
curl -X POST 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/all' \
-H 'Content-Type: application/json' \
-d '[
{
"rules": [
{
"topic": "v1/#",
"permission": "deny",
"action": "all"
}
]
}
]'
```

#### Rule Fields

Each rule can include the following fields:

| Field | Description |
| --------------------------- | ------------------------------------------------------------ |
| **username** / **clientid** | The exact username or client ID this rule applies to (depending on endpoint). |
| **topic** | The MQTT topic this rule applies to. Supports wildcards (`+`, `#`) and [topic placeholders](./authz.md#topic-placeholders). |
| **permission** | Whether to allow or deny the operation request from the current client/user. Options: `allow`, `deny`. |
| **action** | Operation type. Options: `publish`, `subscribe`, `all`. |
| **qos** | (Optional) Allowed QoS levels. Example: `[0,1]`. Default: all levels. |
| **retain** | (Optional) Whether the rule applies to retained messages. Options: `true`, `false`, `all`. |

4 changes: 2 additions & 2 deletions en_US/getting-started/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Container deployment is the quickest way to start exploring EMQX. This quick sta

### Install EMQX Using Installation Package

You can also install EMQX using installation packages on a computer or VM and easily adjust the configurations or run performance tuning. The instructions below use macOS 15 (Sequoia) and arm64 architecure (Apple Silicon) as an example to illustrate the installation steps.
You can also install EMQX using installation packages on a computer or VM and easily adjust the configurations or run performance tuning. The instructions below use macOS 15 (Sequoia) and arm64 architecture (Apple Silicon) as an example to illustrate the installation steps.

::: tip

Expand Down Expand Up @@ -114,7 +114,7 @@ The broker address and the port information should be prepared before testing th

1. Click [MQTTX Web](https://mqttx.app/web-client#/recent_connections) to visit the browser-based MQTTX.

2. Configure and establish the MQTT connection. Click the **+ New Connection** button to enter the configure page:
2. Configure and establish the MQTT connection. Click the **+ New Connection** button to enter the configuration page:

- **Name**: Input a connection name, for example, `MQTTX_Test`.

Expand Down
Loading