5.5.2. User and role management

This section explains how to use Cypher to manage Neo4j role-based access control through users and roles.

5.5.2.1. User Management

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

Table 5.19. User management command syntax
Command Description Required privilege Community Edition Enterprise Edition
SHOW USERS
    [YIELD field1[, field2] [ORDER BY field1 [, field2]] [SKIP n] [LIMIT n]]
    [WHERE expression]

List all users.

SHOW USER

+

+

SHOW USER [name] PRIVILEGES

List the privileges granted to a user.

SHOW PRIVILEGE and SHOW USER

-

+

CREATE USER name [IF NOT EXISTS]
  SET PASSWORD password
  [[SET PASSWORD] CHANGE [NOT] REQUIRED]
  [SET STATUS {ACTIVE | SUSPENDED}]

Create a new user.

CREATE USER

+

+

CREATE OR REPLACE USER name
  SET PASSWORD password
  [[SET PASSWORD] CHANGE [NOT] REQUIRED]
  [SET STATUS {ACTIVE | SUSPENDED}]

Create a new user.

CREATE USER and DROP USER

+

+

ALTER USER name SET {
PASSWORD password
            [[SET PASSWORD] CHANGE [NOT] REQUIRED]
            [SET STATUS {ACTIVE | SUSPENDED} ] |
PASSWORD CHANGE [NOT] REQUIRED
            [SET STATUS {ACTIVE | SUSPENDED}] |
STATUS {ACTIVE | SUSPENDED}

Modify the settings for an existing user.

SET PASSWORD and/or SET USER STATUS

+

+

ALTER CURRENT USER SET PASSWORD FROM original TO password

Change the current user’s password.

None

+

+

DROP USER name [IF EXISTS]

Remove an existing user.

DROP USER

+

+

Listing users

Available users can be seen using SHOW USERS which will produce a table of users with four columns:

Table 5.20. List users output
Column Description Community Edition Enterprise Edition

user

User name

+

+

roles

Roles granted to the user.

-

+

passwordChangeRequired

If true, the user must change their password at the next login.

+

+

suspended

If true, the user is currently suspended (cannot log in).

-

+

Query. 

SHOW USERS

Table 5.21. Result
user roles passwordChangeRequired suspended

1 row

"neo4j"

["admin","PUBLIC"]

true

false

Try this query live.  none SHOW USERS

When first starting a Neo4j DBMS, there is always a single default user neo4j with administrative privileges. It is possible to set the initial password using neo4j-admin set-initial-password, otherwise it is necessary to change the password after first login.

The SHOW USER name PRIVILEGES command is described in Listing privileges.

Creating users

Users can be created using CREATE USER.

Command syntax. 

CREATE [OR REPLACE] USER name [IF NOT EXISTS]
      SET PASSWORD password
      [[SET PASSWORD] CHANGE [NOT] REQUIRED]
      [SET STATUS {ACTIVE | SUSPENDED}]

If the optional SET PASSWORD CHANGE [NOT] REQUIRED is omitted then the default is CHANGE REQUIRED. The default for SET STATUS is ACTIVE. The password can either be a string value or a string parameter.

For example, we can create the user jake in a suspended state and the requirement to change his password.

Query. 

CREATE USER jake
SET PASSWORD 'abc' CHANGE REQUIRED
SET STATUS SUSPENDED

0 rows, System updates: 1

The SET STATUS {ACTIVE | SUSPENDED} part of the command is only available in Enterprise Edition.

Try this query live.  none CREATE USER jake SET PASSWORD 'abc' CHANGE REQUIRED SET STATUS SUSPENDED

The created user will appear on the list provided by SHOW USERS.

Query. 

SHOW USERS YIELD user, suspended, passwordChangeRequired, roles
WHERE user = 'jake'

In this example we also:

  • Reorder the columns using a YIELD clause
  • Filter the results using a WHERE clause to show only the new user
Table 5.22. Result
user suspended passwordChangeRequired roles

1 row

"jake"

true

true

["PUBLIC"]

Try this query live.  none SHOW USERS YIELD user, suspended, passwordChangeRequired, roles WHERE user = 'jake'

In Neo4j Community Edition there are no roles, but all users have implied administrator privileges. In Neo4j Enterprise Edition all users are automatically assigned the PUBLIC role, giving them a base set of privileges.

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

Query. 

CREATE USER jake IF NOT EXISTS SET PASSWORD 'xyz'

0 rows

Try this query live.  none CREATE USER jake IF NOT EXISTS SET PASSWORD 'xyz'

Query. 

CREATE OR REPLACE USER jake
SET PASSWORD 'xyz'

0 rows, System updates: 2

This is equivalent to running DROP USER jake IF EXISTS followed by CREATE USER jake SET PASSWORD 'xyz'.

Try this query live.  none CREATE OR REPLACE USER jake SET PASSWORD 'xyz'

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

Modifying users

Users can be modified using ALTER USER.

Command syntax. 

ALTER USER name SET {
      PASSWORD password
            [[SET PASSWORD] CHANGE [NOT] REQUIRED]
            [SET STATUS {ACTIVE | SUSPENDED} ] |
      PASSWORD CHANGE [NOT] REQUIRED
            [SET STATUS {ACTIVE | SUSPENDED}] |
      STATUS {ACTIVE | SUSPENDED}
}

The password can either be a string value or a string parameter, and is not allowed to be identical to the old password.

For example, we can modify the user jake with a new password and active status as well as remove the requirement to change his password.

Query. 

ALTER USER jake
SET PASSWORD 'abc123' CHANGE NOT REQUIRED
SET STATUS ACTIVE

0 rows, System updates: 1

Try this query live.  none ALTER USER jake SET PASSWORD 'abc123' CHANGE NOT REQUIRED SET STATUS ACTIVE

When altering a user it is only necessary to specify the changes required. For example, leaving out the CHANGE [NOT] REQUIRED part of the query will leave that unchanged.

The SET STATUS {ACTIVE | SUSPENDED} part of the command is only available in Enterprise Edition.

The changes to the user will appear on the list provided by SHOW USERS.

Query. 

SHOW USERS

Table 5.23. Result
user roles passwordChangeRequired suspended

2 rows

"jake"

["PUBLIC"]

false

false

"neo4j"

["admin","PUBLIC"]

true

false

Try this query live.  none SHOW USERS

Changing the current user’s password

Users can change their own password using ALTER CURRENT USER SET PASSWORD. The old password is required in addition to the new one, and either or both can be a string value or a string parameter. When a user executes this command it will change their password as well as set the CHANGE NOT REQUIRED flag.

Query. 

ALTER CURRENT USER
SET PASSWORD FROM 'abc123' TO '123xyz'

0 rows, System updates: 1

Try this query live.  none ALTER CURRENT USER SET PASSWORD FROM 'abc123' TO '123xyz'

This command only works for a logged in user and cannot be run with auth disabled.

Deleting users

Users can be deleted using DROP USER.

Query. 

DROP USER jake

0 rows, System updates: 1

Try this query live.  none DROP USER jake

When a user has been deleted, it will no longer appear on the list provided by SHOW USERS.

Query. 

SHOW USERS

Table 5.24. Result
user roles passwordChangeRequired suspended

1 row

"neo4j"

["admin","PUBLIC"]

true

false

Try this query live.  none SHOW USERS

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

Query. 

DROP USER jake IF EXISTS

0 rows

Try this query live.  none DROP USER jake IF EXISTS

5.5.2.2. Role Management

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.

Table 5.25. Role management command syntax
Command Description Required privilege
SHOW [ALL|POPULATED] ROLES
    [YIELD field1[, field2] [ORDER BY field1 [, field2]] [SKIP n] [LIMIT n]]
    [WHERE expression]

List roles.

SHOW ROLE

SHOW [ALL|POPULATED] ROLES WITH USERS
    [YIELD field1[, field2] [ORDER BY field1 [, field2]] [SKIP n] [LIMIT n]]
    [WHERE expression]

List roles and users assigned to them.

SHOW ROLE and SHOW USER

SHOW ROLE name PRIVILEGES

List the privileges granted to a role.

SHOW ROLE PRIVILEGES

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

Create a new role.

CREATE ROLE

CREATE OR REPLACE ROLE name [AS COPY OF name]

Create a new role.

CREATE ROLE and DROP ROLE

DROP ROLE name [IF EXISTS]

Remove a role.

DROP ROLE

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

Assign roles to users.

ASSIGN ROLE

The PUBLIC role

There exists a special built-in role, PUBLIC, which is assigned to all users. This role cannot be dropped or revoked from any user, but its privileges may be modified. By default, it is assigned the ACCESS privilege on the default database.

In contrast to the PUBLIC role, the other built-in roles can be granted, revoked, dropped and re-created.

Listing roles

Available roles can be seen using SHOW ROLES.

Query. 

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 default database
  • reader - can perform read-only queries on all databases except system.
  • editor - can perform 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.

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

Table 5.26. Result
role

6 rows

"PUBLIC"

"admin"

"architect"

"editor"

"publisher"

"reader"

Try this query live.  none SHOW 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.

Query. 

SHOW POPULATED ROLES
WITH USERS

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

Table 5.27. Result
role member

6 rows

"PUBLIC"

"neo4j"

"PUBLIC"

"jake"

"PUBLIC"

"user1"

"PUBLIC"

"user2"

"PUBLIC"

"user3"

"admin"

"neo4j"

Try this query live.  none SHOW POPULATED ROLES WITH USERS

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

Query. 

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 5.28. Result
role

3 rows

"editor"

"publisher"

"reader"

Try this query live.  none SHOW ROLES YIELD role ORDER BY role WHERE role ENDS WITH 'r'

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

Creating roles

Roles can be created using CREATE ROLE.

Query. 

CREATE ROLE myrole

0 rows, System updates: 1

Try this query live.  none CREATE ROLE myrole

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

Query. 

CREATE ROLE mysecondrole AS COPY OF myrole

0 rows, System updates: 1

Try this query live.  none CREATE ROLE mysecondrole AS COPY OF myrole

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

Query. 

SHOW ROLES

Table 5.29. Result
role

8 rows

"PUBLIC"

"admin"

"architect"

"editor"

"myrole"

"mysecondrole"

"publisher"

"reader"

Try this query live.  none SHOW ROLES

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.

Query. 

CREATE ROLE myrole IF NOT EXISTS

0 rows

Try this query live.  none CREATE ROLE myrole IF NOT EXISTS

Query. 

CREATE OR REPLACE ROLE myrole

0 rows, System updates: 2

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

Try this query live.  none CREATE OR REPLACE ROLE myrole

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

Deleting roles

Roles can be deleted using DROP ROLE command.

Query. 

DROP ROLE mysecondrole

0 rows, System updates: 1

Try this query live.  none DROP ROLE mysecondrole

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

Query. 

SHOW ROLES

Table 5.30. Result
role

6 rows

"PUBLIC"

"admin"

"architect"

"editor"

"publisher"

"reader"

Try this query live.  none SHOW ROLES

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.

Query. 

DROP ROLE mysecondrole IF EXISTS

0 rows

Try this query live.  none DROP ROLE mysecondrole IF EXISTS

Assigning roles to users

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

Query. 

GRANT ROLE myrole TO jake

0 rows, System updates: 1

Try this query live.  none GRANT ROLE myrole TO jake

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

Query. 

SHOW USERS

Table 5.31. Result
user roles passwordChangeRequired suspended

5 rows

"jake"

["myrole","PUBLIC"]

false

false

"neo4j"

["admin","PUBLIC"]

true

false

"user1"

["PUBLIC"]

true

false

"user2"

["PUBLIC"]

true

false

"user3"

["PUBLIC"]

true

false

Try this query live.  none SHOW USERS

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

Query. 

GRANT ROLES role1, role2 TO user1, user2, user3

0 rows, System updates: 6

Try this query live.  none GRANT ROLES role1, role2 TO user1, user2, user3

Query. 

SHOW USERS

Table 5.32. Result
user roles passwordChangeRequired suspended

5 rows

"jake"

["myrole","PUBLIC"]

false

false

"neo4j"

["admin","PUBLIC"]

true

false

"user1"

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

true

false

"user2"

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

true

false

"user3"

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

true

false

Try this query live.  none SHOW USERS

Revoking roles from users

Users can lose access rights by revoking roles from them using REVOKE ROLE.

Query. 

REVOKE ROLE myrole FROM jake

0 rows, System updates: 1

Try this query live.  none REVOKE ROLE myrole FROM jake

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

Query. 

SHOW USERS

Table 5.33. Result
user roles passwordChangeRequired suspended

5 rows

"jake"

["PUBLIC"]

false

false

"neo4j"

["admin","PUBLIC"]

true

false

"user1"

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

true

false

"user2"

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

true

false

"user3"

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

true

false

Try this query live.  none SHOW USERS

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

Query. 

REVOKE ROLES role1, role2 FROM user1, user2, user3

0 rows, System updates: 6

Try this query live.  none REVOKE ROLES role1, role2 FROM user1, user2, user3