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.

1. User management command syntax

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

List all users.

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

For more information, see Listing users.

Required privilege

GRANT SHOW USER

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

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.

For more information, see Listing privileges.

Required privilege

GRANT SHOW PRIVILEGE

GRANT SHOW USER

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

Create a new user.

For more information, see Creating users.

Required privilege

GRANT CREATE USER

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

Create 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 and GRANT DROP USER

Command

RENAME USER

Syntax

RENAME USER name [IF EXISTS] TO otherName

Description

Change the name of a user.

For more information, see Renaming users.

Required privilege

GRANT RENAME USER

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

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.

For more information, see Modifying users.

Required privilege

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

Command

ALTER CURRENT USER SET PASSWORD

Syntax

ALTER CURRENT USER SET PASSWORD FROM original TO password

Description

Change 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

Remove an existing user.

For more information, see Delete users.

Required privilege

GRANT DROP USER

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

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

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.

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.

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

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.

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

4. Creating users

Users can be created using CREATE USER.

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.

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

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

5. Renaming users

Users can be renamed using 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.

6. Modifying users

Users can be modified using 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, 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:

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

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

ALTER USER bob SET HOME DATABASE anotherDb

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

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.

ALTER USER nonExistingUser IF EXISTS SET PASSWORD 'abc123'

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

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.

8. Delete users

Users can be deleted using DROP USER.

DROP USER bob

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:

SHOW USERS
Table 5. Result
user roles passwordChangeRequired suspended home

"neo4j"

["admin","PUBLIC"]

true

false

<null>

Rows: 1