diff --git a/modules/ROOT/pages/access-control/manage-roles.adoc b/modules/ROOT/pages/access-control/manage-roles.adoc index ee8fb0264..48ac86531 100644 --- a/modules/ROOT/pages/access-control/manage-roles.adoc +++ b/modules/ROOT/pages/access-control/manage-roles.adoc @@ -11,7 +11,7 @@ This section explains how to use Cypher to manage roles in Neo4j. 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. +When connected to the DBMS over `bolt`, administration commands are automatically routed to the `system` database. [[access-control-role-syntax]] @@ -25,7 +25,7 @@ m| SHOW ROLES | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- SHOW [ALL\|POPULATED] ROLES [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] @@ -35,21 +35,21 @@ SHOW [ALL\|POPULATED] ROLES | Description a| -List roles. +Lists roles. -When using the `RETURN` clause, the `YIELD` clause is mandatory and may not be omitted. +When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. For more information, see xref::access-control/manage-roles.adoc#access-control-list-roles[Listing roles]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT SHOW ROLE ---- -(see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) +(see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]). |=== @@ -61,7 +61,7 @@ m| SHOW ROLES WITH USERS | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- SHOW [ALL\|POPULATED] ROLES WITH USERS [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] @@ -71,25 +71,28 @@ SHOW [ALL\|POPULATED] ROLES WITH USERS | Description a| -List roles and users assigned to them. +Lists roles and users assigned to them. -When using the `RETURN` clause, the `YIELD` clause is mandatory and may not be omitted. +When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. For more information, see xref::access-control/manage-roles.adoc#access-control-list-roles[Listing roles]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT SHOW ROLE ---- -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] +(see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) + + +[source, privilege, role="noheader"] ---- GRANT SHOW USER ---- -(see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) @@ -104,7 +107,7 @@ m| SHOW ROLE PRIVILEGES | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] [YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] @@ -114,15 +117,15 @@ SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] | Description a| -List the privileges granted to the specified roles. +Lists the privileges granted to the specified roles. -When using the `RETURN` clause, the `YIELD` clause is mandatory and may not be omitted. +When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. For more information, see xref::access-control/manage-privileges.adoc#access-control-list-privileges[Listing privileges]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT SHOW PRIVILEGE ---- @@ -135,25 +138,26 @@ GRANT SHOW PRIVILEGE [cols="<15s,<85"] |=== + | Command m| CREATE ROLE | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- CREATE ROLE name [IF NOT EXISTS] [AS COPY OF otherName] ---- | Description a| -Create a new role. +Creates a new role. For more information, see xref::access-control/manage-roles.adoc#access-control-create-roles[Creating roles]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT CREATE ROLE ---- @@ -169,25 +173,25 @@ m| CREATE OR REPLACE ROLE | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- CREATE OR REPLACE ROLE name [AS COPY OF otherName] ---- | Description a| -Create a new role, or if a role with the same name exists, replace it. +Creates a new role, or if a role with the same name exists, replace it. For more information, see xref::access-control/manage-roles.adoc#access-control-create-roles[Creating roles]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT CREATE ROLE ---- -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT DROP ROLE ---- @@ -205,20 +209,20 @@ m| RENAME ROLE | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- RENAME ROLE name [IF EXISTS] TO otherName ---- | Description a| -Change the name of a role. +Changes the name of a role. For more information, see xref::access-control/manage-roles.adoc#access-control-rename-roles[Renaming roles]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT RENAME ROLE ---- @@ -236,19 +240,19 @@ m| DROP ROLE | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- DROP ROLE name [IF EXISTS] ---- | Description -a| Remove a role. +a| +Removes a role. For more information, see xref::access-control/manage-roles.adoc#access-control-drop-roles[Deleting roles]. | Required privilege -a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT DROP ROLE ---- @@ -260,25 +264,26 @@ GRANT DROP ROLE [cols="<15s,<85"] |=== + | Command m| GRANT ROLE TO | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- GRANT ROLE[S] name[, ...] TO user[, ...] ---- | Description a| -Assign roles to users. +Assigns roles to users. For more information, see xref::access-control/manage-roles.adoc#access-control-assign-roles[Assigning roles to users]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT ASSIGN ROLE ---- @@ -296,20 +301,20 @@ m| REVOKE ROLE | Syntax a| -[source, syntax, role="noheader", indent=0] +[source, syntax, role="noheader"] ---- REVOKE ROLE[S] name[, ...] FROM user[, ...] ---- | Description a| -Remove roles from users. +Removes roles from users. For more information, see xref::access-control/manage-roles.adoc#access-control-revoke-roles[Revoking roles from users]. | Required privilege a| -[source, privilege, role="noheader", indent=0] +[source, privilege, role="noheader"] ---- GRANT REMOVE ROLE ---- @@ -324,18 +329,19 @@ GRANT REMOVE ROLE Available roles can be seen using `SHOW ROLES`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLES ---- This is the same command as `SHOW ALL ROLES`. -When first starting a Neo4j DBMS there are a number of built-in roles: +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 execute privileges for procedures and functions. -* `reader` - can perform traverse and read operations on all databases except `system`. -* `editor` - can perform traverse, read, and write operations on all databases except `system`, but cannot make new labels or relationship types. +* `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 except `system`. +* `editor` - can perform traverse, read, and write operations in all databases except `system`, but cannot create new labels or relationship types. * `publisher` - can do the same as `editor`, but also create new labels and relationship types. * `architect` - can do the same as `publisher` 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. @@ -359,10 +365,10 @@ More information about the built-in roles can be found in xref:5.0@operations-ma 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 roles `WITH USERS` can be appended to the commands. -This will give one result row for each user, so if a role is assigned to two users then it will show up twice in the result. +To see which users are assigned to roles, `WITH USERS` can be added to the command. +This will give a result with one row for each user, so if a role is assigned to two users, then it will show up twice. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW POPULATED ROLES WITH USERS ---- @@ -396,9 +402,9 @@ The table of results will show information about the role and what database it b 2+a|Rows: 6 |=== -It is also possible to filter and sort the results by using `YIELD`, `ORDER BY`, and `WHERE`: +It is also possible to filter and sort the results by using `YIELD`, `ORDER BY` and `WHERE`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLES YIELD role ORDER BY role @@ -408,7 +414,7 @@ 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 using `ORDER BY`. +* The results are ordered by the `action` column using `ORDER BY`. It is also possible to use `SKIP` and `LIMIT` to paginate the results. @@ -433,16 +439,16 @@ The `SHOW ROLE name PRIVILEGES` command is found in xref::access-control/manage- [[access-control-create-roles]] == Creating roles -Roles can be created using `CREATE ROLE`. +Roles can be created using `CREATE ROLE`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- CREATE ROLE name [IF NOT EXISTS] [AS COPY OF otherName] ---- -Roles can be created or replaced by using `CREATE OR REPLACE ROLE`. +Roles can be created or replaced by using `CREATE OR REPLACE ROLE`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- CREATE OR REPLACE ROLE name [AS COPY OF otherName] ---- @@ -460,7 +466,7 @@ A role can be copied, keeping its privileges, using `CREATE ROLE name AS COPY OF .Copy a role ====== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- CREATE ROLE mysecondrole AS COPY OF myrole ---- @@ -470,7 +476,7 @@ Created roles will appear on the list provided by `SHOW ROLES`. .List roles ====== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLES ---- @@ -494,13 +500,12 @@ SHOW ROLES ====== The `CREATE ROLE` command is optionally idempotent, with the default behavior to throw an exception if the role already exists. -Appending `IF NOT EXISTS` to the `CREATE ROLE` command will ensure that no exception is thrown and nothing happens should the role already exist. - +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 if not exists ====== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- CREATE ROLE myrole IF NOT EXISTS ---- @@ -514,7 +519,7 @@ The `CREATE OR REPLACE ROLE` command will result in any existing role being dele .Create or replace role ====== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- CREATE OR REPLACE ROLE myrole ---- @@ -535,12 +540,12 @@ This is equivalent to running `DROP ROLE myrole IF EXISTS` followed by `CREATE R Roles can be renamed using `RENAME ROLE` command: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- RENAME ROLE mysecondrole TO mythirdrole ---- -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLES ---- @@ -573,14 +578,14 @@ The `RENAME ROLE` command is only available when using native authentication and Users can be given access rights by assigning them roles using `GRANT ROLE`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- GRANT ROLE myrole TO bob ---- -The roles assigned to each user can be seen in the list provided by `SHOW USERS`: +The roles assigned to each user can be seen on the list provided by `SHOW USERS`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLES ---- @@ -629,12 +634,12 @@ SHOW ROLES It is possible to assign multiple roles to multiple users in one command: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- GRANT ROLES role1, role2 TO user1, user2, user3 ---- -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLES ---- @@ -687,14 +692,14 @@ SHOW ROLES Users can lose access rights by revoking their role using `REVOKE ROLE`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- REVOKE ROLE myrole FROM bob ---- -The roles revoked from users can no longer be seen in the list provided by `SHOW USERS`: +The roles revoked from users can no longer be seen on the list provided by `SHOW USERS`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLES ---- @@ -743,7 +748,7 @@ SHOW ROLES It is possible to revoke multiple roles from multiple users in one command: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- REVOKE ROLES role1, role2 FROM user1, user2, user3 ---- @@ -754,14 +759,14 @@ REVOKE ROLES role1, role2 FROM user1, user2, user3 Roles can be deleted using `DROP ROLE` command: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- DROP ROLE mythirdrole ---- When a role has been deleted, it will no longer appear on the list provided by `SHOW ROLES`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLES ---- @@ -782,11 +787,10 @@ SHOW ROLES 1+a|Rows: 8 |=== -This command is optionally idempotent, with the default behavior to throw an exception if the role does not exists. -Appending `IF EXISTS` to the command will ensure that no exception is thrown and nothing happens should the role not exist: +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: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- DROP ROLE mythirdrole IF EXISTS ---- -