Managing roles

This section explains how to use Cypher to manage roles in Neo4j.

Roles can be created and managed using a set of Cypher administration commands executed against the system database.

When connected to the DBMS over bolt, administration commands are automatically routed to the system database.

1. Role management command syntax

Command

SHOW ROLES

Syntax

SHOW [ALL|POPULATED] ROLES
    [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]
    [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

Description

List roles.

When using the RETURN clause, the YIELD clause is mandatory and may not be omitted.

For more information, see Listing roles.

Required privilege

GRANT SHOW ROLE

Command

SHOW ROLES WITH USERS

Syntax

SHOW [ALL|POPULATED] ROLES WITH USERS
    [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]
    [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

Description

List roles and users assigned to them.

When using the RETURN clause, the YIELD clause is mandatory and may not be omitted.

For more information, see Listing roles.

Required privilege

GRANT SHOW ROLE

GRANT SHOW USER

Command

SHOW ROLE PRIVILEGES

Syntax

SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]]
    [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]
    [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

Description

List the privileges granted to the specified roles.

When using the RETURN clause, the YIELD clause is mandatory and may not be omitted.

For more information, see Listing privileges.

Required privilege

GRANT SHOW PRIVILEGE

Command

CREATE ROLE

Syntax

CREATE ROLE name [IF NOT EXISTS] [AS COPY OF otherName]

Description

Create a new role.

For more information, see Creating roles.

Required privilege

GRANT CREATE ROLE

Command

CREATE OR REPLACE ROLE

Syntax

CREATE OR REPLACE ROLE name [AS COPY OF otherName]

Description

Create a new role, or if a role with the same name exists, replace it.

For more information, see Creating roles.

Required privilege

GRANT CREATE ROLE and GRANT DROP ROLE

Command

RENAME ROLE

Syntax

RENAME ROLE name [IF EXISTS] TO otherName

Description

Change the name of a role.

For more information, see Renaming roles.

Required privilege

GRANT RENAME ROLE

Command

DROP ROLE

Syntax

DROP ROLE name [IF EXISTS]

Description

Remove a role.

For more information, see Deleting roles.

Required privilege

GRANT DROP ROLE

Command

GRANT ROLE TO

Syntax

GRANT ROLE name[, ...] TO user[, ...]

Description

Assign roles to users.

For more information, see Assigning roles to users.

Required privilege

GRANT ASSIGN ROLE

Command

REVOKE ROLE

Syntax

REVOKE ROLE name[, ...] FROM user[, ...]

Description

Remove roles from users.

For more information, see Revoking roles from users.

Required privilege

GRANT REMOVE ROLE

2. Listing roles

Available roles can be seen using SHOW ROLES:

SHOW ROLES

This is the same command as SHOW ALL ROLES.

When first starting a Neo4j DBMS there are a number of built-in roles:

  • PUBLIC - a role that all users have granted, by default it gives access to the home database

  • reader - can perform traverse and read operations on all databases except system.

  • editor - can perform traverse, read, and write operations on all databases except system, but cannot make new labels or relationship types.

  • publisher - can do the same as editor, but also create new labels and relationship types.

  • architect - can do the same as publisher as well as create and manage indexes and constraints.

  • admin - can do the same as all the above, as well as manage databases, users, roles, and privileges.

Table 1. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"publisher"

"reader"

Rows: 6

More information about the built-in roles can be found in Operations Manual → Built-in roles

There are multiple versions of this command, the default being SHOW ALL ROLES. To only show roles that are assigned to users, the command is SHOW POPULATED ROLES. To see which users are assigned to roles WITH USERS can be appended to the commands. This will give one result row for each user, so if a role is assigned to two users then it will show up twice in the result.

SHOW POPULATED ROLES WITH USERS

The table of results will show information about the role and what database it belongs to:

Table 2. Result
role member

"PUBLIC"

"neo4j"

"PUBLIC"

"bob"

"PUBLIC"

"user1"

"PUBLIC"

"user2"

"PUBLIC"

"user3"

"admin"

"neo4j"

Rows: 6

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

SHOW ROLES YIELD role ORDER BY role WHERE role ENDS WITH 'r'

In this example:

  • The results have been filtered to only return the roles ending in 'r'.

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

It is also possible to use SKIP and LIMIT to paginate the results.

Table 3. Result
role

"editor"

"publisher"

"reader"

Rows: 3

The SHOW ROLE name PRIVILEGES command is found in Listing privileges.

3. Creating roles

Roles can be created using CREATE ROLE.

CREATE ROLE myrole

The following naming rules apply:

  • The first character must be an ASCII alphabetic character.

  • Subsequent characters can be ASCII alphabetic, numeric characters, and underscore.

A role can also be copied, keeping its privileges, using CREATE ROLE AS COPY OF:

CREATE ROLE mysecondrole AS COPY OF myrole

The created roles will appear on the list provided by SHOW ROLES:

SHOW ROLES
Table 4. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"myrole"

"mysecondrole"

"publisher"

"reader"

Rows: 8

These command versions are optionally idempotent, with the default behavior to throw an exception if the role already exists. Appending IF NOT EXISTS to the command will ensure that no exception is thrown and nothing happens should the role already exist. Adding OR REPLACE to the command will result in any existing role being deleted and a new one created:

CREATE ROLE myrole IF NOT EXISTS
CREATE OR REPLACE ROLE myrole

This is equivalent to running DROP ROLE myrole IF EXISTS followed by CREATE ROLE myrole.

  • The IF NOT EXISTS and OR REPLACE parts of this command cannot be used together.

  • Role names are case sensitive.

4. Renaming roles

Roles can be renamed using RENAME ROLE command:

RENAME ROLE mysecondrole TO mythirdrole
SHOW ROLES
Table 5. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"myrole"

"mythirdrole"

"publisher"

"reader"

Rows: 8

The RENAME ROLE command is only available when using native authentication and authorization.

5. Assigning roles to users

Users can be given access rights by assigning them roles using GRANT ROLE:

GRANT ROLE myrole TO bob

The roles assigned to each user can be seen in the list provided by SHOW USERS:

SHOW ROLES
Table 6. Result
user roles passwordChangeRequired suspended home

"bob"

["myrole","PUBLIC"]

false

false

<null>

"neo4j"

["admin","PUBLIC"]

true

false

<null>

"user1"

["PUBLIC"]

true

false

<null>

"user2"

["PUBLIC"]

true

false

<null>

"user3"

["PUBLIC"]

true

false

<null>

Rows: 5

It is possible to assign multiple roles to multiple users in one command:

GRANT ROLES role1, role2 TO user1, user2, user3
SHOW ROLES
Table 7. Result
user roles passwordChangeRequired suspended home

"bob"

["myrole","PUBLIC"]

false

false

<null>

"neo4j"

["admin","PUBLIC"]

true

false

<null>

"user1"

["role1","role2","PUBLIC"]

true

false

<null>

"user2"

["role1","role2","PUBLIC"]

true

false

<null>

"user3"

["role1","role2","PUBLIC"]

true

false

<null>

Rows: 5

6. Revoking roles from users

Users can lose access rights by revoking their role using REVOKE ROLE:

REVOKE ROLE myrole FROM bob

The roles revoked from users can no longer be seen in the list provided by SHOW USERS:

SHOW ROLES
Table 8. Result
user roles passwordChangeRequired suspended home

"bob"

["PUBLIC"]

false

false

<null>

"neo4j"

["admin","PUBLIC"]

true

false

<null>

"user1"

["role1","role2","PUBLIC"]

true

false

<null>

"user2"

["role1","role2","PUBLIC"]

true

false

<null>

"user3"

["role1","role2","PUBLIC"]

true

false

<null>

Rows: 5

It is possible to revoke multiple roles from multiple users in one command:

REVOKE ROLES role1, role2 FROM user1, user2, user3

7. Deleting roles

Roles can be deleted using DROP ROLE command:

DROP ROLE mythirdrole

When a role has been deleted, it will no longer appear on the list provided by SHOW ROLES:

SHOW ROLES
Table 9. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"myrole"

"publisher"

"reader"

Rows: 8

This command is optionally idempotent, with the default behavior to throw an exception if the role does not exists. Appending IF EXISTS to the command will ensure that no exception is thrown and nothing happens should the role not exist:

DROP ROLE mythirdrole IF EXISTS