User and role management

User Management
Role management

User Management

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

Table 1. User management command syntax
Command	Description	Type of user	Available in Community Edition
`SHOW USERS`	List all users	Admin	`+`
`SHOW USER name PRIVILEGES`	List the privileges granted to a user	Admin	-
`CREATE [OR REPLACE] USER name [IF NOT EXISTS] SET PASSWORD 'password' [[SET PASSWORD] CHANGE [NOT] REQUIRED] [SET STATUS {ACTIVE \| SUSPENDED}]`	Create a new user	Admin	`+`
`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	Admin	-
`ALTER CURRENT USER SET PASSWORD FROM 'oldPassword' TO 'newPassword'`	Change the current user’s password	Normal user	`+`
`DROP USER name [IF EXISTS]`	Drop (remove) an existing user	Admin	`+`

Listing users

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

Table 2. List users output
Column	Description	Available in Community Edition
user	user name	`+`
roles	roles granted to the user	-
passwordChangeRequired	if `true` the user must change their password at next login	`+`
suspended	if `true` the user is currently suspended (cannot log in)	-

Query

SHOW USERS

Table 3. Result
user	roles	passwordChangeRequired	suspended
`"neo4j"`	`["admin"]`	`true`	`false`
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.

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 SUSPENDED flag is an enterprise feature.

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

Query

SHOW USERS

Table 4. Result
user	roles	passwordChangeRequired	suspended
`"neo4j"`	`["admin"]`	`true`	`false`
`"jake"`	`[]`	`true`	`true`
Rows: 2

When creating a user, their initial list of roles is empty. In Neo4j community-edition this is not important as all users have implied administator privileges. In Neo4j enterprise-edition a new user like this will have no rights and it is important to grant roles to the user.

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

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.

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

When altering a user it is only necessary to specify the changes required. For example, leaving out any STATUS change part of the query will leave that unchanged.

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

Query

SHOW USERS

Table 5. Result
user	roles	passwordChangeRequired	suspended
`"neo4j"`	`["admin"]`	`true`	`false`
`"jake"`	`[]`	`false`	`false`
Rows: 2

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.

Deleting users

Users can be deleted using DROP USER.

Query

DROP USER jake

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 6. Result
user	roles	passwordChangeRequired	suspended
`"neo4j"`	`["admin"]`	`true`	`false`
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 jake IF EXISTS

0 rows

Role Management

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

The role name PUBLIC is not permitted. This is a system-reserved role, and cannot be used.

Table 7. Role management command syntax
Command	Description
`SHOW [ALL\|POPULATED] ROLES [WITH USERS]`	List roles
`SHOW ROLE name PRIVILEGES`	List the privileges granted to a role
`CREATE [OR REPLACE] ROLE name [IF NOT EXISTS] [AS COPY OF name]`	Create a new role
`DROP ROLE name [IF EXISTS]`	Drop (remove) an existing role
`GRANT ROLE[S] name[, ...] TO user[, ...]`	Assign one or multiple roles to one or multiple users
`REVOKE ROLE[S] name[, ...] FROM user[, ...]`	Remove one or multiple roles from one or multiple users

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:

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 8. Result
role	isBuiltIn
`"admin"`	`true`
`"publisher"`	`true`
`"editor"`	`true`
`"reader"`	`true`
`"architect"`	`true`
Rows: 5

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 9. Result
role	isBuiltIn	member
`"admin"`	`true`	`"neo4j"`
Rows: 1

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

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 10. Result
role	isBuiltIn
`"admin"`	`true`
`"publisher"`	`true`
`"editor"`	`true`
`"reader"`	`true`
`"architect"`	`true`
`"myrole"`	`false`
`"mysecondrole"`	`false`
Rows: 7

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.

Deleting roles

Roles can be deleted using DROP ROLE command.

Query

DROP ROLE mysecondrole

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 11. Result
role	isBuiltIn
`"admin"`	`true`
`"publisher"`	`true`
`"editor"`	`true`
`"reader"`	`true`
`"architect"`	`true`
Rows: 5

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

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

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

Query

SHOW USERS

Table 12. Result
user	roles	passwordChangeRequired	suspended
`"neo4j"`	`["admin"]`	`true`	`false`
`"jake"`	`["myrole"]`	`false`	`false`
`"user1"`	`[]`	`true`	`false`
`"user2"`	`[]`	`true`	`false`
`"user3"`	`[]`	`true`	`false`
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 13. Result
user	roles	passwordChangeRequired	suspended
`"neo4j"`	`["admin"]`	`true`	`false`
`"jake"`	`["myrole"]`	`false`	`false`
`"user1"`	`["role1","role2"]`	`true`	`false`
`"user2"`	`["role2","role1"]`	`true`	`false`
`"user3"`	`["role2","role1"]`	`true`	`false`
Rows: 5

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

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

Query

SHOW USERS

Table 14. Result
user	roles	passwordChangeRequired	suspended
`"neo4j"`	`["admin"]`	`true`	`false`
`"jake"`	`[]`	`false`	`false`
`"user1"`	`["role1","role2"]`	`true`	`false`
`"user2"`	`["role2","role1"]`	`true`	`false`
`"user3"`	`["role2","role1"]`	`true`	`false`
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