Graph and sub-graph access control

Privileges control the access rights to graph elements using a combined whitelist/blacklist mechanism. It is possible to grant access, or deny access, or a combination of the two. The user will be able to access the resource if they have a grant (whitelist) and do not have a deny (blacklist) relevant to that resource. All other combinations of GRANT and DENY will result in the matching path being inaccessible. What this means in practice depends on whether we are talking about a read privilege or a write privilege.

  • If a entity is not accessible due to read privileges, the data will become invisible to attempts to read it. It will appear to the user as if they have a smaller database (smaller graph).

  • If an entity is not accessible due to write privileges, an error will occur on any attempt to write that data.

In this document we will often use the terms 'allows' and 'enables' in seemingly identical ways. However, there is a subtle difference. We will use 'enables' to refer to the consequences of read privileges where a restriction will not cause an error, only a reduction in the apparent graph size. We will use 'allows' to refer to the consequence of write privileges where a restriction can result in an error.

If a user was not also provided with the database ACCESS privilege then access to the entire database will be denied. Information about the database access privilege can be found in The ACCESS privilege.

The GRANT, DENY and REVOKE commands

The administrators can use Cypher® commands to manage Neo4j graph administrative rights. The components of the graph privilege commands are:

  • the command:

    • GRANT – gives privileges to roles.

    • DENY – denies privileges to roles.

    • REVOKE – removes granted or denied privilege from roles.

  • graph-privilege

  • name

    • The graph or graphs to associate the privilege with. Because in Neo4j 4.1 you can have only one graph per database, this command uses the database name to refer to that graph.

      If you delete a database and create a new one with the same name, the new one will NOT have the privileges assigned to the deleted graph.

    • It can be * which means all graphs. Graphs created after this command execution will also be associated with these privileges.

  • entity

    • The graph elements this privilege applies to:

      • NODES label (nodes with the specified label(s)).

      • RELATIONSHIPS type (relationships of the specific type(s)).

      • ELEMENTS label (both nodes and relationships).

    • The label or type can be * which means all labels or types.

    • Multiple labels or types can be specified, comma-separated.

    • Defaults to ELEMENTS * if omitted.

    • Some of the commands for write privileges do not allow an entity part, see Write privileges for details.

  • role[, …​]

    • The role or roles to associate the privilege with, comma-separated.

Table 1. General graph privilege command syntax
Command Description 
GRANT graph-privilege ON GRAPH[S] {* | name[, ...]} [entity] TO role[, ...]

Grant a privilege to one or multiple roles.

 
DENY graph-privilege ON GRAPH[S] {* | name[, ...]} [entity] TO role[, ...]

Deny a privilege to one or multiple roles.

 
REVOKE GRANT graph-privilege ON GRAPH[S] {* | name[, ...]} [entity] FROM role[, ...]

Revoke a granted privilege from one or multiple roles.

 
REVOKE DENY graph-privilege ON GRAPH[S] {* | name[, ...]} [entity] FROM role[, ...]

Revoke a denied privilege from one or multiple roles.

 
REVOKE graph-privilege ON GRAPH[S] {* | name[, ...]} [entity] FROM role[, ...]

Revoke a granted or denied privilege from one or multiple roles.

DENY does NOT erase a granted privilege; they both exist. Use REVOKE if you want to remove a privilege.

The general grant and deny syntax is illustrated in the image below.

grant privileges overview
Figure 1. GRANT and DENY Syntax

A more detailed syntax illustration would be the image below for graph privileges.

grant privileges graph
Figure 2. Syntax of GRANT and DENY Graph Privileges. The { and } are part of the syntax and not used for grouping.

The below image shows the hierarchy between the different graph privileges.

privilege hierarchy graph
Figure 3. Graph privileges hierarchy

Listing privileges

Available privileges can be displayed using the different SHOW PRIVILEGES commands.

Table 2. Show privileges command syntax
Command Description 
SHOW [ALL] PRIVILEGES
    [YIELD field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]

List all privileges.

 
SHOW ROLE name PRIVILEGES
    [YIELD field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]

List privileges for a specific role.

 
SHOW USER [name] PRIVILEGES
    [YIELD field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]

List privileges for a specific user, or the current user.

Examples for listing all privileges

Available privileges for all roles can be displayed using SHOW PRIVILEGES.

Command syntax
SHOW [ALL] PRIVILEGES
    [YIELD field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]
Query
SHOW PRIVILEGES

Lists all privileges for all roles. The table contains columns describing the privilege:

  • access: whether the privilege is granted or denied

  • action: which type of privilege this is: traverse, read, match, write, a database privilege, a dbms privilege or admin

  • resource: what type of scope this privilege applies to: the entire dbms, a database, a graph or sub-graph access

  • graph: the specific database or graph this privilege applies to

  • segment: for sub-graph access control, this describes the scope in terms of labels or relationship types

  • role: the role the privilege is granted to

Table 3. Result
access action resource graph segment role

"GRANTED"

"access"

"database"

"DEFAULT"

"database"

"PUBLIC"

"GRANTED"

"match"

"all_properties"

"*"

"NODE(*)"

"admin"

"GRANTED"

"write"

"graph"

"*"

"NODE(*)"

"admin"

"GRANTED"

"match"

"all_properties"

"*"

"RELATIONSHIP(*)"

"admin"

"GRANTED"

"write"

"graph"

"*"

"RELATIONSHIP(*)"

"admin"

"GRANTED"

"access"

"database"

"*"

"database"

"admin"

"GRANTED"

"admin"

"database"

"*"

"database"

"admin"

"GRANTED"

"constraint"

"database"

"*"

"database"

"admin"

"GRANTED"

"index"

"database"

"*"

"database"

"admin"

"GRANTED"

"token"

"database"

"*"

"database"

"admin"

"GRANTED"

"match"

"all_properties"

"*"

"NODE(*)"

"architect"

"GRANTED"

"write"

"graph"

"*"

"NODE(*)"

"architect"

"GRANTED"

"match"

"all_properties"

"*"

"RELATIONSHIP(*)"

"architect"

"GRANTED"

"write"

"graph"

"*"

"RELATIONSHIP(*)"

"architect"

"GRANTED"

"access"

"database"

"*"

"database"

"architect"

"GRANTED"

"constraint"

"database"

"*"

"database"

"architect"

"GRANTED"

"index"

"database"

"*"

"database"

"architect"

"GRANTED"

"token"

"database"

"*"

"database"

"architect"

"GRANTED"

"match"

"all_properties"

"*"

"NODE(*)"

"editor"

"GRANTED"

"write"

"graph"

"*"

"NODE(*)"

"editor"

"GRANTED"

"match"

"all_properties"

"*"

"RELATIONSHIP(*)"

"editor"

"GRANTED"

"write"

"graph"

"*"

"RELATIONSHIP(*)"

"editor"

"GRANTED"

"access"

"database"

"*"

"database"

"editor"

"DENIED"

"access"

"database"

"neo4j"

"database"

"noAccessUsers"

"GRANTED"

"match"

"all_properties"

"*"

"NODE(*)"

"publisher"

"GRANTED"

"write"

"graph"

"*"

"NODE(*)"

"publisher"

"GRANTED"

"match"

"all_properties"

"*"

"RELATIONSHIP(*)"

"publisher"

"GRANTED"

"write"

"graph"

"*"

"RELATIONSHIP(*)"

"publisher"

"GRANTED"

"access"

"database"

"*"

"database"

"publisher"

"GRANTED"

"token"

"database"

"*"

"database"

"publisher"

"GRANTED"

"match"

"all_properties"

"*"

"NODE(*)"

"reader"

"GRANTED"

"match"

"all_properties"

"*"

"RELATIONSHIP(*)"

"reader"

"GRANTED"

"access"

"database"

"*"

"database"

"reader"

"GRANTED"

"access"

"database"

"neo4j"

"database"

"regularUsers"

Rows: 34

It is also possible to filter and sort the results by using YIELD, ORDER BY and WHERE.

Query
SHOW PRIVILEGES YIELD role, access, action ORDER BY action WHERE role = 'admin'

In this example:

  • The number of columns returned has been reduced with the YIELD clause.

  • The order of the returned columns has been changed.

  • The results have been filtered to only return the admin role using a WHERE clause.

  • The results are ordered by the action column using ORDER BY.

SKIP and LIMIT can also be used to paginate the results.

Table 4. Result
role access action

"admin"

"GRANTED"

"access"

"admin"

"GRANTED"

"admin"

"admin"

"GRANTED"

"constraint"

"admin"

"GRANTED"

"index"

"admin"

"GRANTED"

"match"

"admin"

"GRANTED"

"match"

"admin"

"GRANTED"

"token"

"admin"

"GRANTED"

"write"

"admin"

"GRANTED"

"write"

Rows: 9

WHERE can be used without YIELD

Query
SHOW PRIVILEGES WHERE graph <> '*'

In this example, the WHERE clause is used to filter privileges down to those that target specific graphs only.

Table 5. Result
access action resource graph segment role

"GRANTED"

"access"

"database"

"DEFAULT"

"database"

"PUBLIC"

"DENIED"

"access"

"database"

"neo4j"

"database"

"noAccessUsers"

"GRANTED"

"access"

"database"

"neo4j"

"database"

"regularUsers"

Rows: 3

Examples for listing privileges for specific role

Available privileges for a particular role can be displayed using SHOW ROLE name PRIVILEGES.

Command syntax
SHOW ROLE name PRIVILEGES
    [YIELD field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]
Query
SHOW ROLE regularUsers PRIVILEGES

Lists all privileges for role regularUsers.

Table 6. Result
access action resource graph segment role

"GRANTED"

"access"

"database"

"neo4j"

"database"

"regularUsers"

Rows: 1

Examples for listing privileges for specific user

Available privileges for a particular user can be displayed using SHOW USER name PRIVILEGES.

Please note that if a non-native auth provider like LDAP is in use, SHOW USER PRIVILEGES will only work in a limited capacity; It is only possible for a user to show their own privileges. Other users' privileges cannot be listed when using a non-native auth provider.
Command syntax
SHOW USER [name] PRIVILEGES
    [YIELD field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]
Query
SHOW USER jake PRIVILEGES

Lists all privileges for user jake.

Table 7. Result
access action resource graph segment role user

"GRANTED"

"access"

"database"

"DEFAULT"

"database"

"PUBLIC"

"jake"

"GRANTED"

"access"

"database"

"neo4j"

"database"

"regularUsers"

"jake"

Rows: 2

The same command can be used at all times to review available privileges for the current user. For this purpose, a shorter form of the the command also exists: SHOW USER PRIVILEGES.

Query
SHOW USER PRIVILEGES

The REVOKE command

Privileges that were granted or denied earlier can be revoked using the REVOKE command.

Command syntax
REVOKE
    [ GRANT | DENY ] graph-privilege
    FROM role[, ...]

An example usage of the REVOKE command is given here:

Query
REVOKE GRANT TRAVERSE ON GRAPH neo4j NODES Post FROM regularUsers

0 rows, System updates: 1

While it can be explicitly specified that revoke should remove a GRANT or DENY, it is also possible to revoke either one by not specifying at all as the next example demonstrates. Because of this, if there happen to be a GRANT and a DENY on the same privilege, it would remove both.

Query
REVOKE TRAVERSE ON GRAPH neo4j NODES Payments FROM regularUsers

0 rows, System updates: 2