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