Managing users

This section explains how to use Cypher^® to manage users in Neo4j.

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.

User states

There are two types of user states in the system database:

ACTIVE state (default for new users): Users can log into Neo4j and perform queries according to their privileges.
SUSPENDED state Enterprise Edition:
- Native users who authenticate and authorize against the system graph cannot log into Neo4j. If suspended while using Neo4j, they lose all assigned roles with their privileges, including the PUBLIC role, until reactivated.
- Users who authenticate and authorize against an external ID provider (e.g., LDAP) can still log in. If suspended while using Neo4j, they retain the roles and the privileges assigned by the external provider, including the PUBLIC role. To prevent any of these, you need to use the mechanisms of their identity provider.

User management command syntax

More details about the syntax descriptions can be found here.

Command

SHOW CURRENT USER

Syntax

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

Description

Lists the current user.

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

For more information, see Listing current user.

Required privilege

None

Command

SHOW USERS

Syntax

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

Description

Lists all users.

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

For more information, see Listing users.

Required privilege

GRANT SHOW USER

(see DBMS USER MANAGEMENT privileges)

Command

SHOW USER PRIVILEGES

Syntax

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

Description

Lists 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 must not be omitted.

For more information, see Listing privileges.

Required privilege

GRANT SHOW PRIVILEGE

(see DBMS PRIVILEGE MANAGEMENT privileges)

GRANT SHOW USER

(see DBMS USER MANAGEMENT privileges)

Command

CREATE USER

Syntax

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

Description

Creates a new user.

For more information, see Creating users.

Required privilege

GRANT CREATE USER

(see DBMS USER MANAGEMENT privileges)

Command

CREATE OR REPLACE USER

Syntax

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

Description

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

For more information, see Creating users.

Required privilege

GRANT CREATE USER

(see DBMS USER MANAGEMENT privileges)

GRANT DROP USER

(see DBMS USER MANAGEMENT privileges)

Command

RENAME USER

Syntax

RENAME USER name [IF EXISTS] TO otherName

Description

Changes the name of a user.

For more information, see Renaming users.

Required privilege

GRANT RENAME USER

(see DBMS USER MANAGEMENT privileges)

Command

ALTER USER

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]

Description

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

For more information, see Modifying users.

Required privilege

GRANT SET PASSWORD

[source, privilege, role="noheader"

GRANT SET USER STATUS

GRANT SET USER HOME DATABASE

(see DBMS USER MANAGEMENT privileges)

Command

ALTER CURRENT USER SET PASSWORD

Syntax

ALTER CURRENT USER SET PASSWORD FROM 'oldPassword' TO 'newPassword'

Description

Changes the current user’s password.

For more information, see Changing the current user’s password.

Required privilege

None

Command

DROP USER

Syntax

DROP USER name [IF EXISTS]

Description

Removes an existing user.

For more information, see Delete users.

Required privilege

GRANT DROP USER

(see DBMS USER MANAGEMENT privileges)

The SHOW USER[S] PRIVILEGES command is only available in Neo4j Enterprise Edition. Enterprise Edition

Listing current user

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

Column Description Community Edition Enterprise Edition

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 by the user, or `null` if no home database has 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.

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 by the user, or null if no home database has 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.

SHOW CURRENT USER

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

Listing users

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

Column Description Community Edition Enterprise Edition

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 by the user, or `null` if no home database has been configured. A home database will be resolved if it is either pointing to a database or a database alias. If this database is unavailable and the user does not specify a database to use, they will not be able to log in.

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 by the user, or null if no home database has been configured. A home database will be resolved if it is either pointing to a database or a database alias. If this database is unavailable and the user does not specify a database to use, they will not be able to log in.

SHOW USERS

Table 2. 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 dbms set-initial-password <password>, otherwise it is necessary to change the password after the first login.

Example 1. Show user

This example shows how to:

Reorder the columns using a YIELD clause.
Filter the results using a WHERE clause.

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

Example 2. Show user

It is possible to add a RETURN clause to further manipulate the results after filtering. In this example, the RETURN clause is used to filter out the roles column and rename the user column to adminUser.

SHOW USERS YIELD roles, user
WHERE 'admin' IN roles
RETURN user AS adminUser

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

Creating users

Users can be created using CREATE 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]

Users can be created or replaced using CREATE OR REPLACE USER.

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

For SET PASSWORD:
- The password can either be a string value or a string parameter.
- All passwords are encrypted (hashed) when stored in the Neo4j system database. PLAINTEXT and ENCRYPTED just refer to the format of the password in the Cypher command, i.e. whether Neo4j needs to hash it or it has already been hashed. Consequently, it is never possible to get the plaintext of a password back out of the database. A password can be set in either fashion at any time.
- The optional PLAINTEXT in SET PLAINTEXT PASSWORD has the same behavior as SET PASSWORD.
- The optional ENCRYPTED is used to recreate an existing user when the plaintext password is unknown, but the encrypted password is available in the data/scripts/databasename/restore_metadata.cypher file of a database backup. See Operations Manual → Restore a database backup → Example.
  With ENCRYPTED, the password string is expected to be in the format of <encryption-version>, <hash> or <salt>, where, for example:
  - 0 is the first version and refers to the SHA-256 cryptographic hash function with iterations 1.
  - 1 is the second version and refers to the SHA-256 cryptographic hash function with iterations 1024.
If the optional SET PASSWORD CHANGE [NOT] REQUIRED is omitted, 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.
SET HOME DATABASE can be used to configure a home database for a user. A home database will be resolved if it is either pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for the user.
The SET PASSWORD CHANGE [NOT] REQUIRED, SET STATUS, and SET HOME DATABASE clauses can be applied in any order.

User names are case sensitive. The created user will appear on the list provided by SHOW USERS.

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.

Example 3. Create user

For example, you can create the user jake in a suspended state, with the home database anotherDb, and the requirement to change the password by using the command:

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

Example 4. Create user

Or you can recreate the user jake in an active state, with an encrypted password (taken from the data/scripts/databasename/restore_metadata.cypher of a database backup), and the requirement to not change the password by running:

CREATE USER jake
SET ENCRYPTED PASSWORD '1,6d57a5e0b3317055454e455f96c98c750c77fb371f3f0634a1b8ff2a55c5b825,190ae47c661e0668a0c8be8a21ff78a4a34cdf918cae3c407e907b73932bd16c' CHANGE NOT REQUIRED
SET STATUS ACTIVE

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

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 CREATE USER command will ensure that no exception is thrown and nothing happens should the user already exist.

Example 5. Create user if not exists

CREATE USER jake IF NOT EXISTS
SET PLAINTEXT PASSWORD 'xyz'

The CREATE OR REPLACE USER command will result in any existing user being deleted and a new one created.

Example 6. Create or replace user

CREATE OR REPLACE USER jake
SET PLAINTEXT PASSWORD 'xyz'

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

The CREATE OR REPLACE USER command does not allow the use of IF NOT EXISTS.

Renaming users

Users can be renamed with the RENAME USER command.

RENAME USER jake TO bob

SHOW USERS

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

Modifying users

Users can be modified with ALTER 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 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.
- All passwords are encrypted (hashed) when stored in the Neo4j system database. PLAINTEXT and ENCRYPTED just refer to the format of the password in the Cypher command, i.e. whether Neo4j needs to hash it or it has already been hashed. Consequently, it is never possible to get the plaintext of a password back out of the database. A password can be set in either fashion at any time.
- The optional PLAINTEXT in SET PLAINTEXT PASSWORD has the same behavior as SET PASSWORD.
- The optional ENCRYPTED is used to update an existing user’s password when the plaintext password is unknown, but the encrypted password is available in the data/scripts/databasename/restore_metadata.cypher file of a database backup. See Operations Manual → Restore a database backup → Example.
  With ENCRYPTED, the password string is expected to be in the format of <encryption-version>,<hash> or <salt>, where, for example:
  - 0 is the first version and refers to the SHA-256 cryptographic hash function with iterations 1.
  - 1 is the second version and refers to the SHA-256 cryptographic hash function with iterations 1024.
If the optional SET PASSWORD CHANGE [NOT] REQUIRED is omitted, the default is CHANGE REQUIRED. The SET PASSWORD part is only optional if it directly follows the SET PASSWORD clause.
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. A home database will be resolved if it is either pointing to a database or a database alias. If no home database is set, the DBMS default database is used as the home database for the user.
REMOVE HOME DATABASE is used to unset the home database for a user. This results in the DBMS default database being used as the home database for the user.

For example, you can modify the user bob with a new password and active status, and remove the requirement to change his password:

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

Or you may decide to assign the user bob a different home database:

ALTER USER bob
SET HOME DATABASE anotherDbOrAlias

Or remove the home database from the user bob:

ALTER USER bob
REMOVE HOME DATABASE

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 Neo4j Enterprise Edition. Enterprise Edition

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

SHOW USERS

Table 4. Result
user	roles	passwordChangeRequired	suspended	home
`"bob"`	`["PUBLIC"]`	`false`	`false`	`<null>`
`"neo4j"`	`["admin","PUBLIC"]`	`true`	`false`	`<null>`
Rows: 2

The default behavior of this command is to throw an exception if the user does not exist. Adding an optional parameter IF EXISTS to the command makes it idempotent and ensures that no exception is thrown. Nothing happens should the user not exist.

ALTER USER nonExistingUser IF EXISTS SET PASSWORD 'abc123'

Changing the current user’s password

Users can change their 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.

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

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

Delete users

Users can be deleted with DROP USER.

DROP USER bob

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

However, when a user has been deleted, it will no longer appear on the list provided by SHOW USERS:

SHOW USERS

Table 5. Result
user	roles	passwordChangeRequired	suspended	home
`"neo4j"`	`["admin","PUBLIC"]`	`true`	`false`	`<null>`
Rows: 1