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