Manage roles
Roles 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.
Role management command syntax
For more details about the syntax descriptions, see Cypher syntax for administration commands. |
Command |
|
Syntax |
|
Description |
Lists roles. When using the For more information, see Listing roles. |
Required privilege |
|
Command |
|
Syntax |
|
Description |
Lists roles and users assigned to them. When using the For more information, see Listing roles. |
Required privilege |
For more information, see DBMS ROLE MANAGEMENT privileges.
For more information, see DBMS USER MANAGEMENT privileges. |
Command |
|
Syntax |
|
Description |
Lists the privileges granted to the specified roles. When using the The |
Required privilege |
|
Command |
|
Syntax |
|
Description |
Creates a new role. For more information, see Creating roles. |
Required privilege |
For more information, see DBMS ROLE MANAGEMENT privileges. |
Command |
|
Syntax |
|
Description |
Creates a new role, or if a role with the same name exists, replace it. For more information, see Creating roles. |
Required privilege |
Command |
|
Syntax |
|
Description |
Changes the name of a role. For more information, see Renaming roles. |
Required privilege |
For more information, see DBMS ROLE MANAGEMENT privileges. |
Command |
|
Syntax |
|
Description |
Removes a role. For more information, see Deleting roles. |
Required privilege |
For more information, see DBMS ROLE MANAGEMENT privileges. |
Command |
|
Syntax |
|
Description |
Assigns roles to users. For more information, see Assigning roles to users. |
Required privilege |
For more information, see DBMS ROLE MANAGEMENT privileges. |
Command |
|
Syntax |
|
Description |
Removes roles from users. For more information, see Revoking roles from users. |
Required privilege |
For more information, see DBMS ROLE MANAGEMENT privileges. |
Listing roles
You can view all available roles using the Cypher command SHOW ROLES
, which returns a single column.
Column | Description | Type |
---|---|---|
role |
Role name |
|
SHOW ROLES
This is the same command as SHOW ALL ROLES
.
role |
---|
|
|
|
|
|
|
Rows: 6 |
When first starting a Neo4j DBMS, there are a number of built-in roles:
-
PUBLIC
- a role that all users have granted. By default it gives access to the home database and to execute privileges for procedures and functions. -
reader
- can perform traverse and read operations in all databases exceptsystem
. -
editor
- can perform traverse, read, and write operations in all databases exceptsystem
, but cannot create new labels or relationship types. -
publisher
- can do the same aseditor
, but also create new labels and relationship types. -
architect
- can do the same aspublisher
as well as create and manage indexes and constraints. -
admin
- can do the same as all the above, as well as manage databases, aliases, users, roles, and privileges.
More information about the built-in roles and their privileges can be found in Built-in roles and privileges.
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 which roles, WITH USERS
can be added to the command.
The command produces a row per role per user and yields the following column in addition to the one output by SHOW ROLES
:
Column | Description | Type |
---|---|---|
member |
User name |
|
Since this gives a result with one row for each user, it shows up twice if a role is assigned to two users.
SHOW POPULATED ROLES WITH USERS
The table of results will show information about the role and what database it belongs to:
role | member |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 6 |
It is also possible to filter and sort the results by using YIELD
, ORDER BY
and WHERE
.
SHOW ROLES YIELD role
ORDER BY role
WHERE role ENDS WITH 'r'
In this example:
-
The results have been filtered to only return the roles ending in 'r'.
-
The results are ordered by the
action
column usingORDER BY
.
It is also possible to use SKIP
and LIMIT
to paginate the results.
role |
---|
|
|
|
Rows: 3 |
Creating roles
Roles can be created using CREATE ROLE
:
CREATE ROLE name [IF NOT EXISTS] [AS COPY OF otherName]
Roles can be created or replaced by using CREATE OR REPLACE ROLE
:
CREATE OR REPLACE ROLE name [AS COPY OF otherName]
The following naming rules apply:
|
A role can be copied, keeping its privileges, using CREATE ROLE name AS COPY OF otherName
.
CREATE ROLE mysecondrole AS COPY OF myrole
Created roles will appear on the list provided by SHOW ROLES
.
SHOW ROLES
role |
---|
|
|
|
|
|
|
|
|
Rows: 8 |
The CREATE ROLE
command is optionally idempotent, with the default behavior to throw an exception if the role already exists.
Adding IF NOT EXISTS
to the CREATE ROLE
command will ensure that no exception is thrown and nothing happens should the role already exist.
CREATE ROLE myrole IF NOT EXISTS
The CREATE OR REPLACE ROLE
command will result in any existing role being deleted and a new one created.
CREATE OR REPLACE ROLE myrole
This is equivalent to running DROP ROLE myrole IF EXISTS
followed by CREATE ROLE myrole
.
|
Renaming roles
Roles can be renamed using RENAME ROLE
command:
RENAME ROLE mysecondrole TO mythirdrole
SHOW ROLES
role |
---|
|
|
|
|
|
|
|
|
Rows: 8 |
The |
Assigning roles to users
Users can be given access rights by assigning them roles using GRANT ROLE
:
GRANT ROLE myrole TO bob
The roles assigned to each user can be seen on the list provided by SHOW USERS
:
SHOW USERS
user | roles | passwordChangeRequired | suspended | home |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 5 |
It is possible to assign multiple roles to multiple users in one command:
GRANT ROLES role1, role2 TO user1, user2, user3
SHOW USERS
user | roles | passwordChangeRequired | suspended | home |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 5 |
Common errors, such as attempts to grant roles to users who have already been granted those roles, will lead to notifications. Some of these notifications may be replaced with errors in a future major version of Neo4j. See Status Codes → Notification codes for details on notifications.
Revoking roles from users
Users can lose access rights by revoking their role using REVOKE ROLE
:
REVOKE ROLE myrole FROM bob
The roles revoked from users can no longer be seen on the list provided by SHOW USERS
:
SHOW USERS
user | roles | passwordChangeRequired | suspended | home |
---|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rows: 5 |
It is possible to revoke multiple roles from multiple users in one command:
REVOKE ROLES role1, role2 FROM user1, user2, user3
Common errors, such as misspellings or attempts to revoke roles from users who have not been granted those roles, will lead to notifications. Some of these notifications may be replaced with errors in a future major version of Neo4j. See Status Codes → Notification codes for details on notifications.
Deleting roles
Roles can be deleted using DROP ROLE
command:
DROP ROLE mythirdrole
When a role has been deleted, it will no longer appear on the list provided by SHOW ROLES
:
SHOW ROLES
role |
---|
|
|
|
|
|
|
|
Rows: 8 |
This command is optionally idempotent, with the default behavior to throw an exception if the role does not exist.
Adding IF EXISTS
to the command will ensure that no exception is thrown and nothing happens should the role not exist:
DROP ROLE mythirdrole IF EXISTS