Skip to content

Commit cec7e3f

Browse files
MeggielqkMeggielqk
authored
Merge pull request #3117 from emqx/20250808-authz-mnesia
update(mnesia): Add client ID/username regex
2 parents 475eada + bcf603b commit cec7e3f

File tree

4 files changed

+278
-102
lines changed

4 files changed

+278
-102
lines changed

‎en_US/access-control/authz/mnesia.md‎

Lines changed: 135 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Knowledge about [basic EMQX authorization concepts](./authz.md)
88

99
:::
1010

11-
## Configure with Dashboard
11+
## Create Built-in Database Authorizer via Dashboard
1212

1313
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.
1414

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

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

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

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

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

5252
### Create Authorization Rules via Dashboard
5353

54-
On the **Authorization** page in Dashboard, click the **Permissions** button in the **Actions** column of the **Built-in Database** backend.
54+
You can define authorization rules directly from the EMQX Dashboard by using the **Permissions** page of the **Built-in Database** backend.
55+
56+
#### Access the Permissions Page
57+
58+
1. In the Dashboard, go to the **Authorization** page.
59+
2. In the **Actions** column of the **Built-in Database** backend, click **Permissions**.
5560

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

58-
You can set authorization checks based on the client ID, username, or topic as needed.
63+
#### Authorization Rule Scope
64+
65+
Authorization rules can be configured at three scopes:
66+
67+
- **Client ID**: Apply rules to a specific client ID.
68+
- **Username**: Apply rules to a specific username.
69+
- **All Users**: Apply rules to all clients/users, optionally filtered by patterns or IP ranges.
70+
71+
#### Common Rule Fields
72+
73+
These fields are available for all rule types:
74+
75+
| Field | Description |
76+
| -------------------- | ------------------------------------------------------------ |
77+
| **Action** | The operation type the rule applies to. Options: `Publish`, `Subscribe`, `Publish & Subscribe`. |
78+
| **Permission** | Whether to allow or deny the operation. Options: `Allow`, `Deny`. |
79+
| **Topic** | The MQTT topic this rule applies to. Wildcards (`+`, `#`) are supported. |
80+
| **QoS** | Allowed QoS levels. Multiple values can be selected: `0`, `1`, `2`. |
81+
| **Retain** | Whether the rule applies to retained messages. Options: `true`, `false`, `All`. |
82+
| **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. |
83+
| **Listener** | The listener this rule applies to. Use `{type}:{name}` format, e.g., `tcp:default`, `ws:default`. |
84+
| **Zone** | The Zone in which the rule takes effect. Applicable in multi-Zone deployments. |
85+
86+
#### Fields by Rule Scope
87+
88+
| Rule Scope | Fields |
89+
| ------------- | ------------------------------------------------------------ |
90+
| **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. |
91+
| **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. |
92+
| **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. |
93+
94+
**Example patterns:**
95+
96+
- `^device-user-.*`: Matches usernames starting with `device-user-`.
97+
- `^sensor-.*`: Matches client IDs starting with `sensor-`.
98+
99+
#### Add a Rule
100+
101+
1. On the **Permissions** page, select the target tab: **Client ID**, **Username**, or **All Users**.
102+
2. Click **Add**.
103+
3. Fill in the [common fields](#common-rule-fields) and any [scope-specific fields](#fields-by-rule-scope).
104+
4. (Optional) Click **Add Permission** to add multiple rules. Use the **Up** and **Down** buttons to adjust rule execution order.
105+
5. Click **Add** to save the rule.
106+
107+
#### Manage Multiple Rules (All Users Only)
108+
109+
For **All Users** rules, you can change rule order from the **More** menu in the **Actions** column:
110+
111+
- Move Up
112+
- Move Down
113+
- Move to Top
114+
- Move to Bottom
59115

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

66-
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.
118+
#### Edit and Manage Rules
67119

68-
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.
120+
On the **Permissions** page, you can edit or delete existing rules:
69121

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

72-
Rules are also managed through `/api/v5/authorization/sources/built_in_database` APIs.
125+
### Create Authorization Rules via REST API
73126

74-
Each rule is applied to:
75-
* a particular client identified by clientid
76-
* `/api/v5/authorization/sources/built_in_database/clientid`
77-
* a particular client identified by username
78-
* `/api/v5/authorization/sources/built_in_database/username`
127+
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.
79128

80-
* all clients
81-
* `/api/v5/authorization/sources/built_in_database/all`
129+
#### Endpoints
82130

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

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

86143
```bash
87-
curl -X 'POST' \
88-
'http://localhost:18083/api/v5/authorization/sources/built_in_database/clientid' \
89-
-H 'accept: */*' \
144+
curl -X POST 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/users' \
90145
-H 'Content-Type: application/json' \
91146
-d '[
92-
{
93-
"clientid": "client1",
147+
{
148+
"username": "user1",
149+
"rules": [
150+
{
151+
"topic": "v1/devices/#",
152+
"permission": "allow",
153+
"action": "publish",
154+
"qos": [0,1,2],
155+
"retain": "all"
156+
}
157+
]
158+
}
159+
]'
160+
```
161+
162+
#### Example: Update Rules for a User
163+
164+
```bash
165+
curl -X PUT 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/users/user1' \
166+
-H 'Content-Type: application/json' \
167+
-d '{
168+
"username": "user1",
94169
"rules": [
95170
{
96-
"action": "publish",
171+
"topic": "v1/devices/+/state",
97172
"permission": "allow",
98-
"topic": "test/topic/1"
99-
},
100-
{
101173
"action": "subscribe",
102-
"permission": "allow",
103-
"topic": "test/topic/2"
104-
},
105-
{
106-
"action": "all",
107-
"permission": "deny",
108-
"topic": "eq test/#"
174+
"qos": [0,1],
175+
"retain": "all"
109176
}
110177
]
111-
}
112-
]'
178+
}'
113179
```
114180

115-
Each rule contains:
116-
* `permission`: Whether to allow or deny a certain type of operation request from current client/user; optional values: `allow` or `deny`;
117-
* `action`: Configure the operation corresponding to this rule; optional values: `publish`, `subscribe`, or `all`;
118-
* `topic`: Configure the corresponding to this rule, supporting [topic placeholders](./authz.md#topic-placeholders).
119-
* `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.
120-
* `retain`: (Optional) Used to specify whether the current rule supports retained messages. Value options are `true`, `false`. Default is to allow retained messages.
181+
#### Example: Create Rules for All Users
182+
183+
```bash
184+
curl -X POST 'http://localhost:18083/api/v5/authorization/sources/built_in_database/rules/all' \
185+
-H 'Content-Type: application/json' \
186+
-d '[
187+
{
188+
"rules": [
189+
{
190+
"topic": "v1/#",
191+
"permission": "deny",
192+
"action": "all"
193+
}
194+
]
195+
}
196+
]'
197+
```
198+
199+
#### Rule Fields
200+
201+
Each rule can include the following fields:
202+
203+
| Field | Description |
204+
| --------------------------- | ------------------------------------------------------------ |
205+
| **username** / **clientid** | The exact username or client ID this rule applies to (depending on endpoint). |
206+
| **topic** | The MQTT topic this rule applies to. Supports wildcards (`+`, `#`) and [topic placeholders](./authz.md#topic-placeholders). |
207+
| **permission** | Whether to allow or deny the operation request from the current client/user. Options: `allow`, `deny`. |
208+
| **action** | Operation type. Options: `publish`, `subscribe`, `all`. |
209+
| **qos** | (Optional) Allowed QoS levels. Example: `[0,1]`. Default: all levels. |
210+
| **retain** | (Optional) Whether the rule applies to retained messages. Options: `true`, `false`, `all`. |
121211

‎en_US/getting-started/getting-started.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ Container deployment is the quickest way to start exploring EMQX. This quick sta
5656

5757
### Install EMQX Using Installation Package
5858

59-
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.
59+
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.
6060

6161
::: tip
6262

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

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

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

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

0 commit comments

Comments
 (0)