Graph and sub-graph access control

This section explains how to use Cypher to manage privileges for Neo4j role-based access control and fine-grained security.

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.

1. 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.version} 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.

  • roles

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

Table 1. 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.

grant privileges graph
Figure 1. GRANT and DENY Syntax

2. Listing privileges

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

Command syntax
SHOW [ALL] PRIVILEGES
    [YIELD field1[, field2] [ORDER BY field1 [, field2]] [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 (whitelist or blacklist)

  • 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 2. 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"

34 rows

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 3. 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"

9 rows

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 4. 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"

3 rows

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

Command syntax
SHOW ROLE role PRIVILEGES
    [YIELD field1[, field2] [ORDER BY field1 [, field2]] [SKIP n] [LIMIT n]]
    [WHERE expression]
Query
SHOW ROLE regularUsers PRIVILEGES

Lists all privileges for role 'regularUsers'

Table 5. Result
access action resource graph segment role

"GRANTED"

"access"

"database"

"neo4j"

"database"

"regularUsers"

1 row

Available privileges for a particular user can be seen 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 [user] PRIVILEGES
    [YIELD field1[, field2] [ORDER BY field1 [, field2]] [SKIP n] [LIMIT n]]
    [WHERE expression]
Query
SHOW USER jake PRIVILEGES

Lists all privileges for user 'jake'

Table 6. Result
access action resource graph segment role user

"GRANTED"

"access"

"database"

"DEFAULT"

"database"

"PUBLIC"

"jake"

"GRANTED"

"access"

"database"

"neo4j"

"database"

"regularUsers"

"jake"

2 rows

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

3. 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