User and role management

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 1. User management command syntax
Command Description Required privilege
SHOW CURRENT USER
    [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]
    [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

List the current user.

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

None

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

List all users.

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

SHOW USER

SHOW USER[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]]

List the privileges granted to the specified users or the current user, if no user is specified.

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

SHOW PRIVILEGE and SHOW USER

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

Create a new user.

CREATE USER

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

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

CREATE USER and DROP USER

RENAME USER name [IF EXISTS] TO otherName

Change the name of a user.

RENAME USER

ALTER USER name [IF EXISTS]
  [SET [PLAINTEXT | ENCRYPTED] PASSWORD password]
  [[SET PASSWORD] CHANGE [NOT] REQUIRED]
  [SET STATUS {ACTIVE | SUSPENDED} ]
  [SET HOME DATABASE name]
  [REMOVE HOME DATABASE]

Modify the settings for an existing user. At least one SET or REMOVE clause is required. SET and REMOVE clauses cannot be combined in the same command.

SET PASSWORD, SET USER STATUS and/or SET USER HOME DATABASE

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

The SHOW USER[S] PRIVILEGES command is an enterprise feature.

1.1. Listing current user

The currently logged-in user can be seen using SHOW CURRENT USER which will produce a table with four columns:

Table 2. 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).

-

+

home

The home database configured for the user, or null if no home database have been configured. If this database is unavailable, and the user does not specify a database to use they will not be able to log in.

-

+

Query
SHOW CURRENT USER
Table 3. Result
user roles passwordChangeRequired suspended home

"jake"

["PUBLIC"]

false

false

<null>

Rows: 1

This command is only supported for a logged-in user and will return an empty result if authorization has been disabled.

1.2. Listing users

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

Table 4. 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).

-

+

home

The home database configured for the user, or null if no home database have been configured. If this database is unavailable, and the user does not specify a database to use they will not be able to log in.

-

+

Query
SHOW USERS
Table 5. Result
user roles passwordChangeRequired suspended home

"neo4j"

["admin","PUBLIC"]

true

false

<null>

Rows: 1

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.

1.3. Creating users

Users can be created using CREATE USER.

Command syntax
CREATE [OR REPLACE] USER name [IF NOT EXISTS]
      SET [PLAINTEXT | ENCRYPTED] PASSWORD password
      [[SET PASSWORD] CHANGE [NOT] REQUIRED]
      [SET STATUS {ACTIVE | SUSPENDED}]
      [SET HOME DATABASE name]
  • The SET PASSWORD CHANGE [NOT] REQUIRED and SET STATUS clauses can be applied in any order.

  • For SET PASSWORD:

    • The password can either be a string value or a string parameter.

    • The optional PLAINTEXT in SET PLAINTEXT PASSWORD has the same behaviour as SET PASSWORD.

    • The optional ENCRYPTED can be used to create a user when the plaintext password is unknown but the encrypted password is available (e.g. from a database backup). In this case the password string is expected to be in the format of <encryption-version>,<hash>,<salt>.

  • If the optional SET PASSWORD CHANGE [NOT] REQUIRED is omitted then the default is CHANGE REQUIRED. The SET PASSWORD part is only optional if it directly follows the SET PASSWORD clause.

  • The default for SET STATUS is ACTIVE.

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

Query
CREATE USER jake SET PASSWORD 'abc' CHANGE REQUIRED SET STATUS SUSPENDED SET HOME DATABASE anotherDb

0 rows, System updates: 1

The SET STATUS {ACTIVE | SUSPENDED} and SET HOME DATABASE parts of the command are only available in Enterprise Edition.

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

Query
SHOW USERS YIELD user, suspended, passwordChangeRequired, roles, home 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 6. Result
user suspended passwordChangeRequired roles home

"jake"

true

true

["PUBLIC"]

"anotherDb"

Rows: 1

Query
SHOW USERS YIELD roles, user WHERE "PUBLIC" IN roles RETURN user as publicUsers

It is also possible to add a RETURN clause to further manipulate the results after filtering. In this case it is used to filter out the roles column and rename the users column to publicUsers.

Table 7. Result
publicUsers

"jake"

"neo4j"

Rows: 2

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

Query
CREATE OR REPLACE USER jake SET PLAINTEXT 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'.

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

User names are case sensitive.

1.4. Renaming users

Users can be renamed using the RENAME USER command.

Query
RENAME USER jake TO bob

0 rows, System updates: 1

Query
SHOW USERS
Table 8. Result
user roles passwordChangeRequired suspended home

"bob"

["PUBLIC"]

true

false

<null>

"neo4j"

["admin","PUBLIC"]

true

false

<null>

Rows: 2

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

1.5. Modifying users

Users can be modified using ALTER USER.

Command syntax
ALTER USER name [IF EXISTS]
      [SET [PLAINTEXT | ENCRYPTED] PASSWORD password]
      [[SET PASSWORD] CHANGE [NOT] REQUIRED]
      [SET STATUS {ACTIVE | SUSPENDED}]
      [SET HOME DATABASE name]
      [REMOVE HOME DATABASE name]
  • At least one SET or REMOVE clause is required for the command.

  • SET and REMOVE clauses cannot be combined in the same command.

  • The SET PASSWORD CHANGE [NOT] REQUIRED, SET STATUS, and SET HOME DATABASE clauses can be applied in any order. The SET PASSWORD clause must come first, if used.

  • For SET PASSWORD:

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

    • The optional PLAINTEXT in SET PLAINTEXT PASSWORD has the same behaviour as SET PASSWORD.

    • The optional ENCRYPTED can be used to update a user’s password when the plaintext password is unknown but the encrypted password is available (e.g. from a database backup). In this case the password string is expected to be in the format of <encryption-version>,<hash>,<salt>.

  • For SET PASSWORD CHANGE [NOT] REQUIRED, the SET PASSWORD is only optional if it directly follows the SET PASSWORD clause.

  • SET HOME DATABASE can be used to configure a home database for a user. If no home database is set the default database will used as home database for the user.

  • REMOVE HOME DATABASE is used to unset the home database for a user. This will result in the default database being used as home database for the user.

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

Query
ALTER USER bob SET PASSWORD 'abc123' CHANGE NOT REQUIRED SET STATUS ACTIVE

0 rows, System updates: 1

Or we may decide to assign the user bob a different home database.

Query
ALTER USER bob SET HOME DATABASE anotherDb

0 rows, System updates: 1

Or remove the home database from the user bob.

Query
ALTER USER bob REMOVE HOME DATABASE

0 rows, System updates: 1

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}, SET HOME DATABASE, and REMOVE HOME DATABASE parts of the command are only available in Enterprise Edition.

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

Query
SHOW USERS
Table 9. Result
user roles passwordChangeRequired suspended home

"bob"

["PUBLIC"]

false

false

<null>

"neo4j"

["admin","PUBLIC"]

true

false

<null>

Rows: 2

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
ALTER USER nonExistingUser IF EXISTS SET PASSWORD 'abc123'

0 rows

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

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

1.7. Deleting users

Users can be deleted using DROP USER.

Query
DROP USER bob

0 rows, System updates: 1

Deleting a user will not automatically terminate associated connections, sessions, transactions, or queries.

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

Query
SHOW USERS
Table 10. Result
user roles passwordChangeRequired suspended home

"neo4j"

["admin","PUBLIC"]

true

false

<null>

Rows: 1

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 bob IF EXISTS

0 rows

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 11. Role management command syntax
Command Description Required privilege
SHOW [ALL|POPULATED] ROLES
    [YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
    [WHERE expression]
    [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]

List roles.

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

SHOW ROLE

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]]

List roles and users assigned to them.

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

SHOW ROLE and SHOW USER

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]]

List the privileges granted to the specified roles.

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

SHOW ROLE PRIVILEGES

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

Create a new role.

CREATE ROLE

CREATE OR REPLACE ROLE name [AS COPY OF otherName]

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

CREATE ROLE and DROP ROLE

RENAME ROLE name [IF EXISTS] TO otherName

Change the name of a role.

RENAME ROLE

DROP ROLE name [IF EXISTS]

Remove a role.

DROP ROLE

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

Assign roles to users.

ASSIGN ROLE

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

Remove roles from users.

REMOVE ROLE

2.1. 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 home database.

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

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

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

Table 12. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"publisher"

"reader"

Rows: 6

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

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

"editor"

"publisher"

"reader"

Rows: 3

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

2.3. Creating roles

Roles can be created using CREATE ROLE.

Query
CREATE ROLE myrole

0 rows, System updates: 1

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.

Query
CREATE ROLE mysecondrole AS COPY OF myrole

0 rows, System updates: 1

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

Query
SHOW ROLES
Table 15. 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.

Query
CREATE ROLE myrole IF NOT EXISTS

0 rows

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.

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

Role names are case sensitive.

2.4. Renaming roles

Roles can be renamed using RENAME ROLE command.

Query
RENAME ROLE mysecondrole TO mythirdrole

0 rows, System updates: 1

Query
SHOW ROLES
Table 16. 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.

2.5. Deleting roles

Roles can be deleted using DROP ROLE command.

Query
DROP ROLE mythirdrole

0 rows, System updates: 1

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

Query
SHOW ROLES
Table 17. Result
role

"PUBLIC"

"admin"

"architect"

"editor"

"myrole"

"publisher"

"reader"

Rows: 7

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 mythirdrole IF EXISTS

0 rows

2.6. Assigning roles to users

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

Query
GRANT ROLE myrole TO bob

0 rows, System updates: 1

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

Query
SHOW USERS
Table 18. 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.

Query
GRANT ROLES role1, role2 TO user1, user2, user3

0 rows, System updates: 6

Query
SHOW USERS
Table 19. 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

2.7. Revoking roles from users

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

Query
REVOKE ROLE myrole FROM bob

0 rows, System updates: 1

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

Query
SHOW USERS
Table 20. 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.

Query
REVOKE ROLES role1, role2 FROM user1, user2, user3

0 rows, System updates: 6