Skip to content

Commit 225317a

Browse files
colinbarrymatea16
colinbarry
and
matea16
authored
New fine-grained label based access (#1452)
* chore: Empty commit just to create PR * doc: Update syntax for multi-tenancy setup * docs: Changes for new fine-grained access permissions * docs: Add example for combining rules * docs: Add example for global permissions being overriden * docs: Tidy LBAC docs * docs: Add link to combining rules * docs: Add migration to v3.7 LBAC guide * docs: Apply some minor formatting * docs: Fix minor typos * docs: Add Enterprise to migration page * Apply suggestions from code review --------- Co-authored-by: Matea Pesic <80577904+matea16@users.noreply.github.com>
1 parent 2bf2530 commit 225317a

File tree

4 files changed

+440
-85
lines changed

4 files changed

+440
-85
lines changed

‎pages/database-management/authentication-and-authorization/_meta.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
export default {
22
"users": "Users",
33
"role-based-access-control": "Role-based access control",
4+
"mlbac-migration-guide": "Migrating to v3.7 LBAC",
45
"multiple-roles": "Multiple roles per user and multi-tenant roles",
56
"auth-system-integrations": "Auth system integrations",
67
"impersonate-user": "Impersonate user",

‎pages/database-management/authentication-and-authorization/mlbac-migration-guide.mdx‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: "Migrate to v3.7 label-based access control"
3+
description: "Guide for upgrading from v3.6 label-based access control to v3.7 multi-label based access control"
4+
---
5+
6+
import { Callout } from 'nextra/components'
7+
8+
# Migrate to v3.7 label-based access control <sup style={{ fontSize: '0.6em', color: '#888' }}>Enterprise</sup>
9+
10+
<Callout type="warning">
11+
**Breaking change in v3.7.0**: [Label-based access control](/database-management/authentication-and-authorization/role-based-access-control#fine-grained-access-control) has significant
12+
changes. If you use fine-grained access control, read this guide before
13+
upgrading.
14+
</Callout>
15+
16+
## What's changed?
17+
18+
### Label matching semantics
19+
20+
**Before (v3.6):** Rules matched exact label sets only.
21+
- `GRANT READ ON LABELS :User` matched only `:User`, not `:User:Admin`
22+
23+
**After (v3.7):** Rules use flexible matching modes.
24+
- `GRANT READ ON NODES CONTAINING LABELS :User` now matches `:User`,
25+
`:User:Admin`, etc.
26+
- `MATCHING ANY` (default): Matches vertices with one or more specified labels
27+
- `MATCHING EXACTLY`: Matches vertices with exactly the specified labels
28+
29+
### Permission model change
30+
31+
**Before (v3.6):** Hierarchical permissions
32+
- `NOTHING`, `READ`, `UPDATE`, `CREATE_DELETE`
33+
- `UPDATE` implied `READ`; `CREATE_DELETE` implied everything
34+
35+
**After (v3.7):** Discrete permissions
36+
- `NOTHING`, `CREATE`, `READ`, `UPDATE`, `DELETE`
37+
- Each permission is independent and must be granted explicitly. Any combination
38+
of `CREATE`, `READ`, `UPDATE`, and `DELETE` can be granted.
39+
40+
### Syntax changes
41+
42+
| v3.6 | v3.7 |
43+
|------|------|
44+
| `GRANT READ ON LABELS :User, :Client TO alice` | `GRANT READ ON NODES CONTAINING LABELS :User, :Client TO alice` |
45+
| `GRANT UPDATE ON LABELS :Doc TO bob` | `GRANT READ, UPDATE ON NODES CONTAINING LABELS :Doc TO bob` |
46+
| `GRANT CREATE_DELETE ON EDGE_TYPES :KNOWS TO charlie` | `GRANT CREATE, DELETE ON EDGES OF TYPE :KNOWS TO charlie` |
47+
48+
For more details, please read the guide to
49+
[label-based access control](/database-management/authentication-and-authorization/role-based-access-control#fine-grained-access-control).
50+
51+
## Before upgrading to v3.7
52+
53+
**1. Export current permissions**
54+
55+
```cypher
56+
SHOW USERS;
57+
// For each user
58+
SHOW PRIVILEGES FOR username;
59+
60+
SHOW ROLES;
61+
// For each role
62+
SHOW PRIVILEGES FOR rolename;
63+
```
64+
65+
Save the output: you'll need it to recreate per-label rules.
66+
67+
**2. Back up auth storage**
68+
69+
```bash
70+
# Default location. Adjust if using a custom data directory
71+
cp -r /var/lib/memgraph/auth/backup/location/auth-backup
72+
```
73+
74+
## What gets migrated automatically
75+
76+
Global permissions only (grants on `*`)
77+
78+
| v3.6 Permission | Migrates to v3.7 |
79+
|-----------------|------------------------------|
80+
| NOTHING | NOTHING |
81+
| READ | READ |
82+
| UPDATE | READ, UPDATE |
83+
| CREATE_DELETE | CREATE, READ, UPDATE, DELETE |
84+
85+
Example:
86+
```cypher
87+
// v3.6
88+
GRANT UPDATE ON LABELS * TO alice;
89+
90+
// After automatic migration
91+
GRANT READ, UPDATE ON NODES CONTAINING LABELS * TO alice;
92+
```
93+
94+
## What you must recreate manually
95+
96+
<Callout type="error">
97+
**All per-label and per-edge type rules are dropped** during migration and must
98+
be manually recreated.
99+
Specifically:
100+
- Any `GRANT ... ON LABELS :Label` rules must be recreated
101+
- Any `GRANT ... ON EDGE_TYPES :EdgeType` rules must be recreated
102+
</Callout>
103+
104+
Review your pre-upgrade `SHOW PRIVILEGES` output to identify which users/roles
105+
had per-label permissions. For each permission that you need to recreate:
106+
107+
**1. Determine the equivalent v3.7 permission set:**
108+
- If they had `READ`: `GRANT READ`
109+
- If they had `UPDATE`: `GRANT READ, UPDATE`
110+
- If they had `CREATE_DELETE`: `GRANT CREATE, READ, UPDATE, DELETE`
111+
112+
**2. Choose matching mode:**
113+
- `MATCHING EXACTLY` - vertex must have exactly the specified labels, no more,
114+
no less
115+
- `MATCHING ANY` (default) - vertex must have one or more of the specified labels
116+
117+
**3. Write the new GRANT statement:**
118+
- Use `GRANT ... ON NODES CONTAINING LABELS ... [MATCHING ANY|MATCHING EXACTLY]
119+
TO user` for vertex label rules
120+
- Use `GRANT ... ON EDGES OF TYPE ... TO user` for edge type rules
121+
122+
**Example:**
123+
124+
Your `SHOW PRIVILEGES` output shows `alice` had `READ` on `:User`, and `bob` had
125+
`UPDATE` on `:Document`:
126+
127+
```cypher
128+
GRANT READ ON NODES CONTAINING LABELS :User MATCHING EXACTLY TO alice;
129+
GRANT READ, UPDATE ON NODES CONTAINING LABELS :Document MATCHING EXACTLY TO bob;
130+
```
131+
## After upgrading
132+
133+
**1. Verify global permissions**
134+
135+
```cypher
136+
SHOW USERS;
137+
// For each user
138+
SHOW PRIVILEGES FOR username;
139+
140+
SHOW ROLES;
141+
// For each role
142+
SHOW PRIVILEGES FOR rolename;
143+
```
144+
145+
Check that global (`*`) permissions were migrated correctly.
146+
147+
**2. Recreate per-label rules**
148+
149+
Execute the `GRANT` statements you prepared to recreate all per-label and
150+
per-edge type rules.
151+
152+
**3. Test access**
153+
154+
Connect as each user and verify:
155+
- Access to vertices with different label combinations works as expected
156+
- Edge type access works
157+
158+
159+
## Migration checklist
160+
161+
- [ ] Export all permissions using `SHOW PRIVILEGES`
162+
- [ ] Back up auth storage directory
163+
- [ ] Upgrade to v3.7
164+
- [ ] Verify global `*` permissions migrated
165+
- [ ] Recreate per-label rules
166+
- [ ] Recreate per-edge type rules
167+
- [ ] Test user access
168+
169+
For additional details, refer to the [RBAC documentation] and the complete [summary of changes](/release-notes#memgraph-v370---november-19th-2025) in version 3.7.

0 commit comments

Comments
 (0)