From afc063d2b2b13f69a6f3fd513998dcb92cad223a Mon Sep 17 00:00:00 2001 From: lidiazuin Date: Tue, 26 Jul 2022 14:52:48 +0200 Subject: [PATCH 1/3] merging editorial review and matching formatting --- .../pages/access-control/manage-roles.adoc | 176 ++++++++---------- 1 file changed, 77 insertions(+), 99 deletions(-) diff --git a/modules/ROOT/pages/access-control/manage-roles.adoc b/modules/ROOT/pages/access-control/manage-roles.adoc index eb3575950..e17d61b23 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,24 +35,22 @@ 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]). |=== - [cols="<15s,<85"] |=== @@ -61,7 +59,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,40 +69,38 @@ 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] +(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]) - |=== - [cols="<15s,<85"] |=== - | Command + 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,24 +110,22 @@ 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 ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges]) - |=== - [cols="<15s,<85"] |=== @@ -140,26 +134,25 @@ 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 ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - |=== [cols="<15s,<85"] @@ -169,34 +162,32 @@ 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 ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - |=== - [cols="<15s,<85"] |=== @@ -205,29 +196,27 @@ 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 ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - |=== - [cols="<15s,<85"] |=== @@ -236,55 +225,53 @@ 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 ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - |=== - [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 ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - |=== @@ -296,26 +283,25 @@ 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 ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) - |=== @@ -324,18 +310,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. @@ -355,14 +342,14 @@ When first starting a Neo4j DBMS there are a number of built-in roles: 1+a|Rows: 6 |=== -More information about the built-in roles can be found in xref:4.4@operations-manual:ROOT:authentication-authorization/built-in-roles/index.adoc[Operations Manual -> Built-in roles] +More information about the built-in roles can be found in xref:4.4@operations-manual:ROOT:authentication-authorization/built-in-roles/index.adoc[Operations Manual -> Built-in roles]. 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 +383,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 +395,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 +420,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 +447,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 +457,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,36 +481,28 @@ 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 ---- - ====== - The `CREATE OR REPLACE ROLE` command will result in any existing role being deleted and a new one created. - .Create or replace role ====== - -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- CREATE OR REPLACE ROLE myrole ---- This is equivalent to running `DROP ROLE myrole IF EXISTS` followed by `CREATE ROLE myrole`. - ====== - [NOTE] ==== * The `CREATE OR REPLACE ROLE` command does not allow you to use the `IF NOT EXISTS`. @@ -535,12 +514,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 +552,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 +608,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 +666,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 +722,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 +733,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 +761,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 ---- - From 2623029fd1b313399add8b1b578e69ec331e8fc9 Mon Sep 17 00:00:00 2001 From: lidiazuin Date: Tue, 26 Jul 2022 14:59:42 +0200 Subject: [PATCH 2/3] updating with fixes --- modules/ROOT/pages/access-control/manage-roles.adoc | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/access-control/manage-roles.adoc b/modules/ROOT/pages/access-control/manage-roles.adoc index e17d61b23..0d0d488d6 100644 --- a/modules/ROOT/pages/access-control/manage-roles.adoc +++ b/modules/ROOT/pages/access-control/manage-roles.adoc @@ -82,8 +82,10 @@ a| GRANT SHOW ROLE ---- +[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 @@ -92,10 +94,11 @@ GRANT SHOW USER (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) |=== + [cols="<15s,<85"] |=== -| Command +| Command m| SHOW ROLE PRIVILEGES | Syntax @@ -126,9 +129,11 @@ GRANT SHOW PRIVILEGE (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges]) |=== + [cols="<15s,<85"] |=== + | Command m| CREATE ROLE @@ -245,6 +250,7 @@ GRANT DROP ROLE (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) |=== + [cols="<15s,<85"] |=== @@ -491,18 +497,22 @@ 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 ====== + [source, cypher, role=noplay] ---- CREATE OR REPLACE ROLE myrole ---- This is equivalent to running `DROP ROLE myrole IF EXISTS` followed by `CREATE ROLE myrole`. + ====== + [NOTE] ==== * The `CREATE OR REPLACE ROLE` command does not allow you to use the `IF NOT EXISTS`. From 6b26c615986ba5575d465cff78dcfe64e1b9d2fa Mon Sep 17 00:00:00 2001 From: lidiazuin Date: Tue, 26 Jul 2022 15:03:31 +0200 Subject: [PATCH 3/3] updates --- .../ROOT/pages/access-control/manage-roles.adoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/modules/ROOT/pages/access-control/manage-roles.adoc b/modules/ROOT/pages/access-control/manage-roles.adoc index 0d0d488d6..a7639379a 100644 --- a/modules/ROOT/pages/access-control/manage-roles.adoc +++ b/modules/ROOT/pages/access-control/manage-roles.adoc @@ -48,9 +48,11 @@ a| GRANT SHOW ROLE ---- + (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]). |=== + [cols="<15s,<85"] |=== @@ -91,7 +93,9 @@ GRANT SHOW ROLE GRANT SHOW USER ---- + (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-user-management[DBMS USER MANAGEMENT privileges]) + |=== @@ -127,6 +131,7 @@ GRANT SHOW PRIVILEGE ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges]) + |=== @@ -158,6 +163,7 @@ GRANT CREATE ROLE ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) + |=== [cols="<15s,<85"] @@ -191,8 +197,10 @@ GRANT DROP ROLE ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) + |=== + [cols="<15s,<85"] |=== @@ -220,8 +228,10 @@ GRANT RENAME ROLE ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) + |=== + [cols="<15s,<85"] |=== @@ -248,6 +258,7 @@ GRANT DROP ROLE ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) + |=== @@ -278,6 +289,7 @@ GRANT ASSIGN ROLE ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) + |=== @@ -308,6 +320,7 @@ GRANT REMOVE ROLE ---- (see xref::access-control/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]) + |=== @@ -491,15 +504,18 @@ Adding `IF NOT EXISTS` to the `CREATE ROLE` command will ensure that no exceptio .Create role if not exists ====== + [source, cypher, role=noplay] ---- 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 ======