Manage users
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
For more details about the syntax descriptions, see Cypher syntax for administration commands. |
Command |
|
Syntax |
|
Description |
Lists the current user. When using the For more information, see Listing current user. |
Required privilege |
None |
Command |
|
Syntax |
|
Description |
Lists all users. When using the For more information, see Listing users. |
Required privilege |
|
Command |
|
Syntax |
|
Description |
Lists the privileges granted to the specified users or the current user if no user is specified. When using the For more information, see Listing privileges. |
Required privilege |
|
Command |
|
Syntax |
|
Description |
Creates a new user. For more information, see Creating users. |
Required privilege |
|
Command |
|
Syntax |
|
Description |
Creates a new user, or if a user with the same name exists, replace it. For more information, see Creating users. |
Required privilege |
|
Command |
|
Syntax |
|
Description |
Changes the name of a user. For more information, see Renaming users. |
Required privilege |
|
Command |
|
Syntax |
|
Description |
Modifies the settings for an existing user.
At least one For more information, see Modifying users. |
Required privilege |
[source, privilege, role="noheader" GRANT SET USER STATUS
|
Command |
|
Syntax |
|
Description |
Changes the current user’s password. For more information, see Changing the current user’s password. |
Required privilege |
None |
Command |
|
Syntax |
|
Description |
Removes an existing user. For more information, see Delete users. |
Required privilege |
|
The |
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 | Type | Community Edition | Enterprise Edition |
---|---|---|---|---|
user |
User name |
|
||
roles |
Roles granted to the user. Will return |
|
||
passwordChangeRequired |
If |
|
||
suspended |
If Will return |
|
||
home |
The home database configured by the user, or Will return |
|
SHOW CURRENT USER
user | roles | passwordChangeRequired | suspended | home |
---|---|---|---|---|
|
|
|
|
|
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 | Type | Community Edition | Enterprise Edition |
---|---|---|---|---|
user |
User name |
|
||
roles |
Roles granted to the user. Will return |
|
||
passwordChangeRequired |
If |
|
||
suspended |
If Will return |
|
||
home |
The home database configured by the user, or Will return |
|
SHOW USERS
user | roles | passwordChangeRequired | suspended | home |
---|---|---|---|---|
|
|
|
|
|
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.
This example shows how to:
-
Reorder the columns using a
YIELD
clause. -
Filter the results using a
WHERE
clause.
SHOW USER YIELD user, suspended, passwordChangeRequired, roles, home
WHERE user = 'jake'
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 |
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. -
The default Neo4j password length is at least 8 characters.
-
All passwords are encrypted (hashed) when stored in the Neo4j
system
database.PLAINTEXT
andENCRYPTED
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
inSET PLAINTEXT PASSWORD
has the same behavior asSET 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 Restore a database backup → Example.
WithENCRYPTED
, the password string is expected to be in the format of<encryption-version>,<hash>,<salt>
, where, for example:-
0
is the first version and refers to theSHA-256
cryptographic hash function with iterations1
. -
1
is the second version and refers to theSHA-256
cryptographic hash function with iterations1024
.
-
-
-
If the optional
SET PASSWORD CHANGE [NOT] REQUIRED
is omitted, the default isCHANGE REQUIRED
. TheSET PASSWORD
part is only optional if it directly follows theSET PASSWORD
clause. -
The default for
SET STATUS
isACTIVE
. -
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
, andSET HOME DATABASE
clauses can be applied in any order.
User names are case sensitive.
The created user will appear on the list provided by
|
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 'abcd1234' CHANGE REQUIRED
SET STATUS SUSPENDED
SET HOME DATABASE anotherDb
Or you can create 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 |
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.
CREATE USER jake IF NOT EXISTS
SET PLAINTEXT PASSWORD 'abcd1234'
The CREATE OR REPLACE USER
command will result in any existing user being deleted and a new one created.
CREATE OR REPLACE USER jake
SET PLAINTEXT PASSWORD 'abcd1234'
This is equivalent to running DROP USER jake IF EXISTS
followed by CREATE USER jake SET PASSWORD 'abcd1234'
.
The |
Renaming users
Users can be renamed with the RENAME USER
command.
RENAME USER jake TO bob
SHOW USERS
user | roles | passwordChangeRequired | suspended | home |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
Rows: 2 |
The |
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
orREMOVE
clause is required for the command. -
SET
andREMOVE
clauses cannot be combined in the same command. -
The
SET PASSWORD CHANGE [NOT] REQUIRED
,SET STATUS
, andSET HOME DATABASE
clauses can be applied in any order. TheSET 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
andENCRYPTED
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
inSET PLAINTEXT PASSWORD
has the same behavior asSET 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 Restore a database backup → Example.
WithENCRYPTED
, the password string is expected to be in the format of<encryption-version>,<hash>,<salt>
, where, for example:-
0
is the first version and refers to theSHA-256
cryptographic hash function with iterations1
. -
1
is the second version and refers to theSHA-256
cryptographic hash function with iterations1024
.
-
-
-
If the optional
SET PASSWORD CHANGE [NOT] REQUIRED
is omitted, the default isCHANGE REQUIRED
. TheSET PASSWORD
part is only optional if it directly follows theSET PASSWORD
clause. -
For
SET PASSWORD CHANGE [NOT] REQUIRED
, theSET PASSWORD
is only optional if it directly follows theSET 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 'abcd5678' 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 |
The |
The changes to the user will appear on the list provided by SHOW USERS
:
SHOW USERS
user | roles | passwordChangeRequired | suspended | home |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
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 'abcd1234'
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 'password1' TO 'password2'
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
user | roles | passwordChangeRequired | suspended | home |
---|---|---|---|---|
|
|
|
|
|
Rows: 1 |