Enterprise Edition

A subset of this functionality is also available in Community Edition. The table below includes an indication of which functions this is valid for. Refer to Community Edition for a complete description.

In Neo4j, native user and role management are managed by using built-in procedures through Cypher. This section gives a list of all the security procedures for user management along with some simple examples. Use Neo4j Browser or Neo4j Cypher Shell to run the examples provided.

The following table lists the available procedures:

Procedure name Description Executable by role(s) Available in Community Edition

dbms.security.activateUser

Activate a suspended user

admin

dbms.security.addRoleToUser

Assign a role to the user

admin

dbms.security.changePassword

Change the current user’s password

reader,editor,publisher,architect,admin

dbms.security.changeUserPassword

Change the given user’s password

admin

dbms.security.createRole

Create a new role

admin

dbms.security.createUser

Create a new user

admin

dbms.security.deleteRole

Delete the specified role. Any role assignments will be removed

admin

dbms.security.deleteUser

Delete the specified user

admin

dbms.security.listRoles

List all available roles

admin

dbms.security.listRolesForUser

List all roles assigned to the specified user

admin

dbms.security.listUsers

List all local users

admin

dbms.security.listUsersForRole

List all users currently assigned the specified role

admin

dbms.security.removeRoleFromUser

Unassign a role from the user

admin

dbms.security.suspendUser

Suspend the specified user

admin

Activate a suspended user

An administrator is able to activate a suspended user so that the user is once again able to access the data in their original capacity.

Syntax:

CALL dbms.security.activateUser(username, requirePasswordChange)

Arguments:

Name Type Description

username

String

This is the username of the user to be activated.

requirePasswordChange

Boolean

This is optional, with a default of true. If this is true, (i) the user will be forced to change their password when they next log in, and (ii) until the user has changed their password, they will be forbidden from performing any other operation.

Exceptions:

The current user is not an administrator.

The username does not exist in the system.

The username matches that of the current user (i.e. activating the current user is not permitted).

Considerations:

This is an idempotent procedure.
Example 1. Activate a suspended user

The following example activates a user with the username 'jackgreen'. When the user 'jackgreen' next logs in, he will be required to change his password.

CALL dbms.security.activateUser('jackgreen')

Assign a role to the user

An administrator is able to assign a role to any user in the system, thus allowing the user to perform a series of actions upon the data.

Syntax:

CALL dbms.security.addRoleToUser(roleName, username)

Arguments:

Name Type Description

roleName

String

This is the name of the role to be assigned to the user.

username

String

This is the username of the user who is to be assigned the role.

Exceptions:

The current user is not an administrator.

The username does not exist in the system.

The username contains characters other than alphanumeric characters and the ‘_’ character.

The role name does not exist in the system.

The role name contains characters other than alphanumeric characters and the ‘_’ character.

Considerations:

This is an idempotent procedure.
Example 2. Assign a role to the user

The following example assigns the role publisher to the user with username 'johnsmith'.

CALL dbms.security.addRoleToUser('publisher', 'johnsmith')

Change the current user’s password

The procedure dbms.security.changePassword(newPassword, requirePasswordChange) has been entirely removed since the corresponding Cypher administration command also requires the old password, and thus is more secure. Please use ALTER CURRENT USER SET PASSWORD FROM 'oldPassword' TO 'newPassword', documented in the Cypher Manual, instead.

Change the given user’s password

An administrator is able to change the password of any user within the system. Alternatively, the current user may change their own password.

Syntax:

CALL dbms.security.changeUserPassword(username, newPassword, requirePasswordChange)

Arguments:

Name Type Description

username

String

This is the username of the user whose password is to be changed.

newPassword

String

This is the new password for the user.

requirePasswordChange

Boolean

This is optional, with a default of true. If this is true, (i) the user will be forced to change their password when they next log in, and (ii) until the user has changed their password, they will be forbidden from performing any other operation.

Exceptions:

The current user is not an administrator and the username does not match that of the current user.

The username does not exist in the system.

The password is the empty string.

The password is the same as the user’s previous password.

Considerations:

This procedure may be invoked by the current user to change their own password, irrespective of whether or not the current user is an administrator.

This procedure may be invoked by an administrator to change another user’s password.

In addition to changing the user’s password, this will terminate with immediate effect all of the user’s sessions and roll back any running transactions.
Example 3. Change a given user’s password

The following example changes the password of the user with the username 'joebloggs' to 'h6u4%kr'. When the user 'joebloggs' next logs in, he will be required to change his password.

CALL dbms.security.changeUserPassword('joebloggs', 'h6u4%kr')

Create a new role

An administrator is able to create custom roles in the system.

Syntax:

CALL dbms.security.createRole(roleName)

Arguments:

Name Type Description

roleName

String

This is the name of the role to be created.

Exceptions:

The current user is not an administrator.

The role name already exists in the system.

The role name is empty.

The role name contains characters other than alphanumeric characters and the ‘_’ character.

The role name matches one of the native roles: reader, publisher, architect, and admin.
Example 4. Create a new role

The following example creates a new custom role.

CALL dbms.security.createRole('operator')

Create a new user

An administrator is able to create a new user. This action ought to be followed by assigning a role to the user, which is described here.

Syntax:

CALL dbms.security.createUser(username, password, requirePasswordChange)

Arguments:

Name Type Description

username

String

This is the user’s username.

password

String

This is the user’s password.

requirePasswordChange

Boolean

This is optional, with a default of true. If this is true, (i) the user will be forced to change their password when they log in for the first time, and (ii) until the user has changed their password, they will be forbidden from performing any other operation.

Exceptions:

The current user is not an administrator.

The username either contains characters other than the ASCII characters between ! and ~, or contains : and ,.

The username is already in use within the system.

The password is the empty string.
Example 5. Create a new user

The following example creates a user with the username 'johnsmith' and password 'h6u4%kr'. When the user 'johnsmith' logs in for the first time, he will be required to change his password.

CALL dbms.security.createUser('johnsmith', 'h6u4%kr')

Delete the specified role

An administrator is able to delete roles from the system.

Syntax:

CALL dbms.security.deleteRole(roleName)

Arguments:

Name Type Description

roleName

String

This is the name of the role to be deleted.

Exceptions:

The current user is not an administrator.

The role name does not exist in the system.

The role name matches one of the native roles: reader, publisher, architect, and admin.

Considerations:

Any role assignments will be removed.
Example 6. Delete the specified role

The following example deletes the custom role 'operator' from the system.

CALL dbms.security.deleteRole('operator')

Delete the specified user

An administrator is able to delete permanently a user from the system. It is not possible to undo this action, so, if in any doubt, consider suspending the user instead.

Syntax:

CALL dbms.security.deleteUser(username)

Arguments:

Name Type Description

username

String

This is the username of the user to be deleted.

Exceptions:

The current user is not an administrator.

The username does not exist in the system.

The username matches that of the current user (i.e. deleting the current user is not permitted).

Considerations:

It is not necessary to remove any assigned roles from the user prior to deleting the user.

Deleting a user will terminate with immediate effect all of the user’s sessions and roll back any running transactions.

As it is not possible for the current user to delete themselves, there will always be at least one administrator in the system.
Example 7. Delete the specified user

The following example deletes a user with the username 'janebrown'.

CALL dbms.security.deleteUser('janebrown')

List all available roles

An administrator is able to view all assigned users for each role in the system.

Syntax:

CALL dbms.security.listRoles()

Returns:

Name Type Description

role

String

This is the name of the role.

users

List<String>

This is a list of the usernames of all users who have been assigned the role.

Exceptions:

The current user is not an administrator.
Example 8. List all available roles

The following example shows, for each role in the system, the name of the role and the usernames of all assigned users.

CALL dbms.security.listRoles()
+------------------------------+
| role        | users          |
+------------------------------+
| "reader"    | ["bill"]       |
| "architect" | []             |
| "admin"     | ["neo4j"]      |
| "publisher" | ["john","bob"] |
+------------------------------+
4 rows

List all roles assigned to the specified user

Any active user is able to view all of their assigned roles. An administrator is able to view all assigned roles for any user in the system.

Syntax:

CALL dbms.security.listRolesForUser(username)

Arguments:

Name Type Description

username

String

This is the username of the user.

Returns:

Name Type Description

value

String

This returns all roles assigned to the requested user.

Exceptions:

The current user is not an administrator and the username does not match that of the current user.

The username does not exist in the system.

Considerations:

This procedure may be invoked by the current user to view their roles, irrespective of whether or not the current user is an administrator.

This procedure may be invoked by an administrator to view the roles for another user.
Example 9. List all roles assigned to the specified user

The following example lists all the roles for the user with username 'johnsmith', who has the roles reader and publisher.

CALL dbms.security.listRolesForUser('johnsmith')
+-------------+
| value       |
+-------------+
| "reader"    |
| "publisher" |
+-------------+
2 rows

List all local users

An administrator is able to view the details of every user in the system.

Syntax:

CALL dbms.security.listUsers()

Returns:

Name Type Description

username

String

This is the user’s username.

roles

List<String>

This is a list of roles assigned to the user.

flags

List<String>

This is a series of flags indicating whether the user is suspended or needs to change their password.

Exceptions:

The current user is not an administrator.
Example 10. List all local users

The following example shows, for each user in the system, the username, the roles assigned to the user, and whether the user is suspended or needs to change their password.

CALL dbms.security.listUsers()
+---------------------------------------------------------------------+
| username | roles                     | flags                        |
+---------------------------------------------------------------------+
| "neo4j"  | ["admin"]                 | []                           |
| "anne"   | []                        | ["password_change_required"] |
| "bill"   | ["reader"]                | ["is_suspended"]             |
| "john"   | ["architect","publisher"] | []                           |
+---------------------------------------------------------------------+
4 rows

List all users currently assigned the specified role

An administrator is able to view all assigned users for a role.

Syntax:

CALL dbms.security.listUsersForRole(roleName)

Arguments:

Name Type Description

roleName

String

This is the name of the role.

Returns:

Name Type Description

value

String

This returns all assigned users for the requested role.

Exceptions:

The current user is not an administrator.

The role name does not exist in the system.
Example 11. List all users currently assigned the specified role

The following example lists all the assigned users - 'bill' and 'anne' - for the role publisher.

CALL dbms.security.listUsersForRole('publisher')
+--------+
| value  |
+--------+
| "bill" |
| "anne" |
+--------+
2 rows

Unassign a role from the user

An administrator is able to remove a role from any user in the system, thus preventing the user from performing upon the data any actions prescribed by the role.

Syntax:

CALL dbms.security.removeRoleFromUser(roleName, username)

Arguments:

Name Type Description

roleName

String

This is the name of the role which is to be removed from the user.

username

String

This is the username of the user from which the role is to be removed.

Exceptions:

The current user is not an administrator.

The username does not exist in the system.

The role name does not exist in the system.

The username is that of the current user and the role is admin.

Considerations:

If the username is that of the current user and the role name provided is admin, an error will be thrown; i.e. the current user may not be demoted from being an administrator.

As it is not possible for the current user to remove the admin role from themselves, there will always be at least one administrator in the system.

This is an idempotent procedure.
Example 12. Unassign a role from the user

The following example removes the role publisher from the user with username 'johnsmith'.

CALL dbms.security.removeRoleFromUser('publisher', 'johnsmith')

Suspend the specified user

An administrator is able to suspend a user from the system. The suspended user may be activated at a later stage.

Syntax:

CALL dbms.security.suspendUser(username)

Arguments:

Name Type Description

username

String

This is the username of the user to be suspended.

Exceptions:

The current user is not an administrator.

The username does not exist in the system.

The username matches that of the current user (i.e. suspending the current user is not permitted).

Considerations:

Suspending a user will terminate with immediate effect all of the user’s sessions and roll back any running transactions.

All of the suspended user’s attributes — assigned roles and password — will remain intact.

A suspended user will not be able to log on to the system.

As it is not possible for the current user to suspend themselves, there will always be at least one active administrator in the system.

This is an idempotent procedure.
Example 13. Suspend the specified user

The following example suspends a user with the username 'billjones'.

CALL dbms.security.suspendUser('billjones')