You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To make the page consistent with other pages.
---------
Co-authored-by: Reneta Popova <[email protected]>
Co-authored-by: Phil Wright <[email protected]>
It is possible to create read privileges that are based on properties of nodes.
15
+
Property-based access control grants permissions to users to read node properties based on property/value conditions.
15
16
Each property-based privilege can only be restricted by a single property.
16
-
To specify the property/value conditions of the read privilege the `pattern` syntax described below is used,
17
-
for more information about read privilege syntax see xref:authentication-authorization/privileges-reads.adoc[read privilege] page.
17
+
For information about read privileges and their syntax, see xref:authentication-authorization/privileges-reads.adoc[Read privileges].
18
+
19
+
[IMPORTANT]
20
+
====
21
+
When using property-based access control, ensure the property used for the rule cannot be modified.
22
+
Users who can change this property can affect the granted property-based privileges.
23
+
====
24
+
25
+
26
+
== Syntax
27
+
28
+
To specify the property/value conditions of the read privilege, you can use the following syntax:
29
+
30
+
[source, syntax, role="noheader"]
31
+
----
32
+
{GRANT | DENY | REVOKE [GRANT | DENY]}
33
+
[IMMUTABLE]
34
+
{MATCH | READ | TRAVERSE}
35
+
ON { HOME GRAPH | GRAPH[S] { * | name[, ...] } }
36
+
[
37
+
ELEMENT[S] { * | label-or-rel-type[, ...] }
38
+
| NODE[S] { * | label[, ...] }
39
+
| RELATIONSHIP[S] { * | rel-type[, ...] }
40
+
| FOR {
41
+
42
+
([var][:label["|" ...]] "{" property: value "}")
43
+
| (var[:label["|" ...]])
44
+
WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } }
45
+
| (var[:label["|" ...]]
46
+
WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } } )
47
+
}
48
+
49
+
{TO | FROM} role[, ...]
50
+
----
51
+
52
+
53
+
== Performance considerations
18
54
19
55
Adding property-based access control may lead to a significant performance overhead in certain scenarios.
20
56
See xref:authentication-authorization/limitations.adoc#property-based-access-control-limitations[Limitations] for more detailed information.
21
-
To reduce the performance impact, it is recommended to use the Block Storage format as it is better optimized for the kind of read required for the resolution of property-based privileges.
22
57
23
-
Some of the factors that can worsen the impact on performance when having property rules are:
58
+
When having property rules, the following factors can worsen the impact on performance:
24
59
25
-
* The number of properties on the nodes concerned (more properties = greater performance impact)
60
+
* The number of properties on the nodes concerned (more properties = greater performance impact).
26
61
* The number of property-based privileges (more property-based privileges = greater performance impact).
27
-
* The type of the privilege: `TRAVERSE` property-based privileges have a greater performance impact than `READ` property-based privileges.
28
-
* The type of storage medium in operation. The performance impact of property-based privileges will be considerably amplified by accessing disc storage.
62
+
* The type of the privilege: `TRAVERSE` property-based privileges have greater performance impact than `READ` property-based privileges.
63
+
* The type of storage medium in operation. The impact of the property-based privileges on performance is considerably amplified by accessing disc storage.
64
+
65
+
To reduce the performance impact, it is recommended to use the `block` storage format as it is better optimized for the kind of read required for the resolution of property-based privileges.
29
66
30
67
For performance-critical scenarios, it is recommended to design privileges based on labels.
31
-
For more information, see xref:authentication-authorization/privileges-reads.adoc[Read privileges].
32
68
33
-
[IMPORTANT]
34
-
====
35
-
When using property-based access control, ensure the property used for the rule cannot be modified.
36
-
Users who can change this property can affect the granted property-based privileges.
37
-
====
38
69
39
-
Pattern syntax:
70
+
== Examples
71
+
72
+
You can use the following syntax for defining a property-based privilege:
73
+
40
74
[source, syntax, role="noheader"]
41
75
----
42
-
([var][:label["|" ...]] "{" property: value "}")
43
-
| (var[:label["|" ...]]) WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } }
44
-
| (var[:label["|" ...]] WHERE [NOT] var.property { { = | <> | > | >= | < | <= } value | IS NULL | IS NOT NULL | IN { "["[value[, ...]]"]" | listParam } } )
76
+
GRANT privilege-name ON GRAPH graph-name FOR pattern TO role-name
45
77
----
78
+
46
79
[NOTE]
47
80
====
48
-
For more details about the syntax descriptions, see xref:database-administration/syntax.adoc[Cypher syntax for administration commands].
49
-
====
50
-
[NOTE]
51
-
====
52
-
The role does not need to have `READ` privilege for the property used by the property-based privilege.
81
+
The user role does not need to have `READ` privilege for the property used by the property-based privilege.
53
82
====
54
-
You can use this pattern syntax for defining read privileges as follows:
55
83
56
-
[source, syntax, role="noheader"]
57
-
----
58
-
GRANT ... ON GRAPH ... FOR pattern TO ...
59
-
----
84
+
=== Grant a property-based privilege on a specific property using its value
60
85
86
+
The following example shows how to grant permission to `READ` the `address` property on `Email` or `Website` nodes with domain `exampledomain.com` to role `regularUsers`:
61
87
62
-
.Granting permission to `READ` the `address` property on `Email` or `Website` nodes with domain `exampledomain.com` to role `regularUsers`:
63
88
[source, syntax, role="noheader"]
64
89
----
65
90
GRANT READ { address } ON GRAPH * FOR (n:Email|Website) WHERE n.domain = 'exampledomain.com' TO regularUsers
66
91
----
92
+
67
93
Alternatively, you can use the following syntax:
94
+
68
95
[source, syntax, role="noheader"]
69
96
----
70
97
GRANT READ { address } ON GRAPH * FOR (:Email|Website {domain: 'exampledomain.com'}) TO regularUsers
71
98
----
72
99
73
100
74
-
.Granting permission to `TRAVERSE` nodes with label `Email` where property `classification` is `NULL` to role `regularUsers`:
101
+
=== Grant a property-based privilege using `NULL`
102
+
103
+
The following example shows how to grant permission to `TRAVERSE` nodes with the label `Email` where property `classification` is `NULL` to role `regularUsers`:
104
+
75
105
[source, syntax, role="noheader"]
76
106
----
77
107
GRANT TRAVERSE ON GRAPH * FOR (n:Email) WHERE n.classification IS NULL TO regularUsers
78
108
----
79
109
80
-
.Denying permission to `READ` and `TRAVERSE` nodes where the property `classification` is different from `UNCLASSIFIED` to role `regularUsers`:
110
+
=== Deny a property-based privilege using a comparison operator
111
+
112
+
The following example shows how to deny permission to `READ` and `TRAVERSE` nodes where the property `classification` is different from `UNCLASSIFIED` to role `regularUsers`:
113
+
81
114
[source, syntax, role="noheader"]
82
115
----
83
116
DENY MATCH {*} ON GRAPH * FOR (n) WHERE n.classification <> 'UNCLASSIFIED' TO regularUsers
84
117
----
85
118
86
-
.Granting permission to `READ` all properties on nodes where the property `securityLevel` is higher than `3` to role `regularUsers`:
119
+
=== Grant a property-based privilege on all properties using a property value
120
+
121
+
The following example shows how to grant permission to `READ` all properties on nodes where the property `securityLevel` is higher than `3` to role `regularUsers`:
122
+
87
123
[source, syntax, role="noheader"]
88
124
----
89
125
GRANT READ {*} ON GRAPH * FOR (n) WHERE n.securityLevel > 3 TO regularUsers
90
126
----
127
+
91
128
[NOTE]
92
129
====
93
130
The role `regularUsers` does not need to have `READ` privilege for the property `securityLevel` used by the property-based privilege.
94
131
====
95
132
96
-
.Denying permission to `READ` all properties on nodes where the property `classification` is not included in the list of `[UNCLASSIFIED, PUBLIC]`
133
+
=== Deny a property-based privilege using a list of values
134
+
135
+
The following example shows how to deny permission to `READ` all properties on nodes where the property `classification` is not included in the list of `[UNCLASSIFIED, PUBLIC]`:
136
+
97
137
[source, syntax, role="noheader"]
98
138
----
99
139
DENY READ {*} ON GRAPH * FOR (n) WHERE NOT n.classification IN ['UNCLASSIFIED', 'PUBLIC'] TO regularUsers
100
140
----
101
141
102
-
.Granting permission to `READ` all properties on nodes where the property `createdAt` is later than the current date to role `regularUsers`:
142
+
// The last two examples were added in 5.26.
143
+
144
+
=== Grant a property-based privilege using temporal value
145
+
146
+
The following example shows how to grant permission to `READ` all properties on nodes where the property `createdAt` is later than the current date:
147
+
103
148
[source, syntax, role="noheader"]
104
149
----
105
150
GRANT READ {*} ON GRAPH * FOR (n) WHERE n.createdAt > date() TO regularUsers
106
151
----
152
+
107
153
[NOTE]
108
154
====
109
155
The `date()` function is evaluated, and the value used to evaluate the privilege is the date when the property-based privilege is created.
110
156
Keep this in mind when designing your property rules, and use the `SHOW PRIVILEGES AS COMMANDS` command to check the stored value.
111
157
This is essential when revoking property-based privileges containing evaluated function values like `date()`.
112
158
====
159
+
113
160
[NOTE]
114
161
====
115
162
Not all temporal values are comparable, see link:{neo4j-docs-base-uri}/cypher-manual/current/syntax/operators/#cypher-ordering[Cypher Manual -> Syntax -> Operators -> Ordering and comparison of values].
116
163
====
117
164
118
-
.Show the privilege created by the command in the previous example as a revoke command:
165
+
You can show the privilege created by the command in the previous example as a revoke command by running:
166
+
119
167
[source, syntax, role="noheader"]
120
168
----
121
169
SHOW ROLE regularUsers PRIVILEGES AS REVOKE COMMANDS
122
170
----
171
+
123
172
.Result
124
173
[options="header,footer", width="100%", cols="m"]
125
174
|===
126
175
|command
127
176
|"REVOKE GRANT READ {*} ON GRAPH * FOR (n) WHERE n.createdAt > date('2024-10-25') FROM `regularUsers`"
0 commit comments