From c91a0ca1358e28d59332dfead1d66c9eea9b5860 Mon Sep 17 00:00:00 2001 From: lidiazuin Date: Tue, 26 Jul 2022 13:53:30 +0200 Subject: [PATCH 1/2] merging editorial review and matching formatting --- .../access-control/manage-privileges.adoc | 176 ++++++++---------- 1 file changed, 82 insertions(+), 94 deletions(-) diff --git a/modules/ROOT/pages/access-control/manage-privileges.adoc b/modules/ROOT/pages/access-control/manage-privileges.adoc index 633232291..6fddf76c2 100644 --- a/modules/ROOT/pages/access-control/manage-privileges.adoc +++ b/modules/ROOT/pages/access-control/manage-privileges.adoc @@ -9,13 +9,13 @@ This section explains how to use Cypher to manage privileges for Neo4j role-base -- Privileges control the access rights to graph elements using a combined allowlist/denylist mechanism. -It is possible to grant access, or deny access, or a combination of the two. -The user will be able to access the resource if they have a grant (whitelist) and do not have a deny (blacklist) relevant to that resource. +It is possible to grant or deny access, or use a combination of the two. +The user will be able to access the resource if they have a `GRANT` (allowlist) and do not have a `DENY` (denylist) relevant to that resource. All other combinations of `GRANT` and `DENY` will result in the matching path being inaccessible. -What this means in practice depends on whether we are talking about a xref::access-control/privileges-reads.adoc[read privilege] or a xref::access-control/privileges-writes.adoc[write privilege]. +What this means in practice depends on whether we are talking about a xref::access-control/privileges-reads.adoc[read privilege] or a xref::access-control/privileges-writes.adoc[write privilege]: -* If a entity is not accessible due to xref::access-control/privileges-reads.adoc[read privileges], the data will become invisible to attempts to read it. -It will appear to the user as if they have a smaller database (smaller graph). +* If an entity is not accessible due to xref::access-control/privileges-reads.adoc[read privileges], the data will become invisible. +It will appear to the user as if they had a smaller database (smaller graph). * If an entity is not accessible due to xref::access-control/privileges-writes.adoc[write privileges], an error will occur on any attempt to write that data. [NOTE] @@ -27,14 +27,14 @@ We will use _'allows'_ to refer to the consequence of xref::access-control/privi [NOTE] ==== -If a user was not also provided with the database `ACCESS` privilege then access to the entire database will be denied. +If a user was not also provided with the database `ACCESS` privilege, then access to the entire database will be denied. Information about the database access privilege can be found in xref::access-control/database-administration.adoc#access-control-database-administration-access[The ACCESS privilege]. ==== [role=enterprise-edition] [[access-control-graph-privileges]] -== Graph privilege commands (`GRANT`, `DENY`, and `REVOKE`) +== Graph privilege commands (`GRANT`, `DENY` and `REVOKE`) Administrators can use Cypher commands to manage Neo4j graph administrative rights. The components of the graph privilege commands are: @@ -42,7 +42,7 @@ The components of the graph privilege commands are: * the command: ** `GRANT` – gives privileges to roles. ** `DENY` – denies privileges to roles. -** `REVOKE` – removes granted or denied privilege from roles. +** `REVOKE` – removes granted or denied privileges from roles. * _graph-privilege_ ** Can be either a xref::access-control/privileges-reads.adoc[read privilege] or xref::access-control/privileges-writes.adoc[write privilege]. @@ -54,14 +54,14 @@ When using an alias, the command will be executed on the resolved graph. + [NOTE] ==== -If you delete a database and create a new one with the same name, the new one will _NOT_ have the privileges assigned to the deleted graph. +If you delete a database and create a new one with the same name, the new one will _NOT_ have the privileges previously assigned to the deleted graph. ==== -** It can be `+*+` which means all graphs. +** It can be `+*+`, which means all graphs. Graphs created after this command execution will also be associated with these privileges. ** `HOME GRAPH` refers to the graph associated with the home database for that user. -The default database will be used as home database if a user does not have a home database configured. -If the user's home database changes for any reason after privileges have been created then these privileges will be associated with the graph attached to the new database. +The default database will be used as home database if a user does not have one configured. +If the user's home database changes for any reason after privileges have been created, then these privileges will be associated with the graph attached to the new database. This can be quite powerful as it allows permissions to be switched from one graph to another simply by changing a user's home database. * _entity_ @@ -69,14 +69,14 @@ This can be quite powerful as it allows permissions to be switched from one grap *** `NODES` label (nodes with the specified label(s)). *** `RELATIONSHIPS` type (relationships of the specific type(s)). *** `ELEMENTS` label (both nodes and relationships). -** The label or type can be `+*+` which means all labels or types. +** The label or type can be referred with `+*+`, which means all labels or types. ** Multiple labels or types can be specified, comma-separated. ** Defaults to `ELEMENTS` `+*+` if omitted. -** Some of the commands for write privileges do not allow an _entity_ part, see xref::access-control/privileges-writes.adoc[Write privileges] for details. +** Some of the commands for write privileges do not allow an _entity_ part. +See xref::access-control/privileges-writes.adoc[Write privileges] for details. * _role[, ...]_ ** The role or roles to associate the privilege with, comma-separated. - .General grant +ON GRAPH+ privilege syntax [cols="<15s,<85"] |=== @@ -92,11 +92,10 @@ GRANT graph-privilege ON { HOME GRAPH \| GRAPH[S] { * \| name[, ...] } } [entity ---- | Description -a| Grant a privilege to one or multiple roles. +a| Grants a privilege to one or multiple roles. |=== - .General deny +ON GRAPH+ privilege syntax [cols="<15s,<85"] |=== @@ -112,11 +111,10 @@ DENY graph-privilege ON { HOME GRAPH \| GRAPH[S] { * \| name[, ...] } } [entity] ---- | Description -a| Deny a privilege to one or multiple roles. +a| Denies a privilege to one or multiple roles. |=== - .General revoke +ON GRAPH+ privilege syntax [cols="<15s,<85"] |=== @@ -130,13 +128,11 @@ a| ---- REVOKE GRANT graph-privilege ON { HOME GRAPH \| GRAPH[S] { * \| name[, ...] } } [entity] FROM role[, ...] ---- - | Description -a| Revoke a granted privilege from one or multiple roles. +a| Revokes a granted privilege from one or multiple roles. |=== - .General revoke +ON GRAPH+ privilege syntax [cols="<15s,<85"] |=== @@ -152,11 +148,10 @@ REVOKE DENY graph-privilege ON { HOME GRAPH \| GRAPH[S] {* \| name[, ...] } } [e ---- | Description -a| Revoke a denied privilege from one or multiple roles. +a| Revokes a denied privilege from one or multiple roles. |=== - .General revoke +ON GRAPH+ privilege syntax [cols="<15s,<85"] |=== @@ -172,8 +167,7 @@ REVOKE graph-privilege ON { HOME GRAPH \| GRAPH[S] { * \| name[, ...] } } [entit ---- | Description -| Revoke a granted or denied privilege from one or multiple roles. - +| Revokes a granted or denied privilege from one or multiple roles. |=== [NOTE] @@ -182,15 +176,15 @@ REVOKE graph-privilege ON { HOME GRAPH \| GRAPH[S] { * \| name[, ...] } } [entit Use `REVOKE` if you want to remove a privilege. ==== -The general grant and deny syntax is illustrated in the following image: +The general `GRANT` and `DENY` syntaxes are illustrated in the following image: image::privileges_grant_and_deny_syntax.png[title="GRANT and DENY Syntax"] -A more detailed syntax illustration would be the following image for graph privileges: +A more detailed syntax illustration for graph privileges would be the following: image::privileges_on_graph_syntax.png[title="Syntax of GRANT and DENY Graph Privileges. The `{` and `}` are part of the syntax and not used for grouping."] -The following image shows the hierarchy between the different graph privileges: +The following image shows the hierarchy between different graph privileges: image::privileges_hierarchy.png[title="Graph privileges hierarchy"] @@ -199,9 +193,9 @@ image::privileges_hierarchy.png[title="Graph privileges hierarchy"] [[access-control-list-privileges]] == Listing privileges -Available privileges can be displayed using the different `SHOW PRIVILEGES` commands. +Available privileges can be displayed using the different `SHOW PRIVILEGE[S]` commands. -.Show privileges syntax +.Show privileges command syntax [cols="<15s,<85"] |=== @@ -217,13 +211,11 @@ SHOW [ALL] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] [WHERE expression] [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ---- - | Description | List all privileges. |=== - .Show role privileges syntax [cols="<15s,<85"] |=== @@ -242,11 +234,10 @@ SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] ---- | Description -| List privileges for a specific role. +| Lists privileges for a specific role. |=== - .Show user privileges syntax [cols="<15s,<85"] |=== @@ -265,40 +256,40 @@ SHOW USER[S] [name[, ...]] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] ---- | Description -| List privileges for a specific user, or the current user. +| Lists privileges for a specific user, or the current user. -| Note -| -It is only possible for a user to show their own privileges. +[NOTE] +==== +Please note that it is only possible for a user to show their own privileges. Therefore, if a non-native auth provider like LDAP is in use, `SHOW USER PRIVILEGES` will only work in a limited capacity. -Other users' privileges cannot be listed when using a non-native auth provider. +Other users' privileges cannot be listed when using a non-native auth provider. +==== |=== +When using the `RETURN` clause, the `YIELD` clause is mandatory and must not be omitted. -When using the `RETURN` clause, the `YIELD` clause is mandatory and may not be omitted. - -For an easy overview of the existing privileges, it is recommended to use the `AS COMMANDS` version of the show command. +For an easy overview of the existing privileges, it is recommended to use the `AS COMMANDS` version of the `SHOW` command. This returns the privileges as the commands that are granted or denied. -Omitting the `AS COMMANDS` clause instead gives the result as multiple columns describing the privilege: +When omitting the `AS COMMANDS` clause, results will include multiple columns describing privileges: * `access`: whether the privilege is granted or denied. -* `action`: which type of privilege this is, for example traverse, read, index management, or role management. -* `resource`: what type of scope this privilege applies to: the entire dbms, a database, a graph or sub-graph access. +* `action`: which type of privilege this is, for example traverse, read, index management or role management. +* `resource`: what type of scope this privilege applies to, i.e. the entire DBMS, a specific database, a graph or sub-graph access. * `graph`: the specific database or graph this privilege applies to. -* `segment`: when applicable, the scope this privilege applies to: labels, relationship types, procedures, functions, or transactions. -* `role`: the role the privilege is granted to. +* `segment`: when applicable, this privilege applies to labels, relationship types, procedures, functions or transactions. +* `role`: the role a privilege is granted to. [role=enterprise-edition] [[access-control-list-all-privileges]] === Examples for listing all privileges -Available privileges can be displayed using the different `SHOW PRIVILEGES` commands. +Available privileges can be displayed using the different `SHOW PRIVILEGE[S]` commands. .Command syntax -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW [ALL] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] [WHERE expression] @@ -306,10 +297,10 @@ SHOW [ALL] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] SHOW [ALL] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n] [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] + [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n] ---- -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW PRIVILEGES ---- @@ -604,7 +595,7 @@ Lists all privileges for all roles: 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 PRIVILEGES YIELD role, access, action, segment ORDER BY action @@ -691,12 +682,11 @@ In this example: 4+a|Rows: 12 |=== -`WHERE` can be used without `YIELD`: +`WHERE` can also be used without `YIELD`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- -SHOW PRIVILEGES -WHERE graph <> '*' +SHOW PRIVILEGES WHERE graph <> '*' ---- In this example, the `WHERE` clause is used to filter privileges down to those that target specific graphs only. @@ -736,11 +726,11 @@ In this example, the `WHERE` clause is used to filter privileges down to those t |=== Aggregations in the `RETURN` clause can be used to group privileges. -In this case, by user and granted / denied: +In this case, by user and `GRANTED` or `DENIED`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- -SHOW PRIVILEGES YIELD * RETURN role, access, collect([graph, resource, segment, action]) AS privileges +SHOW PRIVILEGES YIELD * RETURN role, access, collect([graph, resource, segment, action]) as privileges ---- .Result @@ -788,7 +778,7 @@ SHOW PRIVILEGES YIELD * RETURN role, access, collect([graph, resource, segment, The `RETURN` clause can also be used to order and paginate the results, which is useful when combined with `YIELD` and `WHERE`. In this example the query returns privileges for display five-per-page, and skips the first five to display the second page. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW PRIVILEGES YIELD * RETURN * ORDER BY role SKIP 5 LIMIT 5 ---- @@ -841,9 +831,9 @@ SHOW PRIVILEGES YIELD * RETURN * ORDER BY role SKIP 5 LIMIT 5 6+a|Rows: 5 |=== -Available privileges can also be output as Cypher commands, by appending `AS COMMAND[S]` to the show command: +Available privileges can also be displayed as Cypher commands by adding `AS COMMAND[S]`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW PRIVILEGES AS COMMANDS ---- @@ -892,7 +882,7 @@ a|Rows: 35 Like other `SHOW` commands, the output can also be processed using `YIELD` / `WHERE` / `RETURN`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW PRIVILEGES AS COMMANDS WHERE command CONTAINS 'MANAGEMENT' @@ -913,9 +903,9 @@ WHERE command CONTAINS 'MANAGEMENT' a|Rows: 8 |=== -It is also possible to get the privilege commands formatted for revoking instead of granting or denying the privileges: +It is also possible to get the privileges listed as revoking commands instead of granting or denying: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW PRIVILEGES AS REVOKE COMMANDS ---- @@ -969,9 +959,9 @@ For more info about revoking privileges, please see xref::access-control/manage- [[access-control-list-privileges-role]] === Examples for listing privileges for specific roles -Available privileges for specific roles can be displayed using `SHOW ROLE name PRIVILEGES`. +Available privileges for specific roles can be displayed using `SHOW ROLE name PRIVILEGE[S]`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] [WHERE expression] @@ -982,7 +972,7 @@ SHOW ROLE[S] name[, ...] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ---- -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLE regularUsers PRIVILEGES ---- @@ -1009,7 +999,7 @@ Lists all privileges for role `regularUsers`. 6+a|Rows: 1 |=== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLES regularUsers, noAccessUsers PRIVILEGES ---- @@ -1043,7 +1033,7 @@ Lists all privileges for roles `regularUsers` and `noAccessUsers`. 6+a|Rows: 2 |=== -Similar to the other show privilege commands, the available privileges for roles can also be output as Cypher commands with the optional `AS COMMAND[S]`. +Similar to the other `SHOW PRIVILEGES` commands, the available privileges for roles can also be listed as Cypher commands with the optional `AS COMMAND[S]`. .Result [options="header,footer", width="100%", cols="m"] @@ -1063,12 +1053,11 @@ Similar to the other show privilege commands, the available privileges for roles a|Rows: 11 |=== -The output can be processed using `YIELD` / `WHERE` / `RETURN` here as well. +The output can be processed using `YIELD` / `WHERE` / `RETURN` here as well: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- -SHOW ROLE architect PRIVILEGES AS COMMANDS -WHERE command CONTAINS 'MATCH' +SHOW ROLE architect PRIVILEGES AS COMMANDS WHERE command CONTAINS 'MATCH' ---- .Result @@ -1080,10 +1069,10 @@ WHERE command CONTAINS 'MATCH' |Rows: 2 |=== -Again, is it possible to get the privilege commands formatted for revoking instead of granting or denying the privileges. +Again, it is possible to get the privileges listed as revoking commands instead of granting or denying. For more info about revoking privileges, please see xref::access-control/manage-privileges.adoc#access-control-revoke-privileges[The REVOKE command]. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW ROLE reader PRIVILEGES AS REVOKE COMMANDS ---- @@ -1107,12 +1096,11 @@ Available privileges for specific users can be displayed using `SHOW USER name P [NOTE] ==== -Please note that if a non-native auth provider like LDAP is in use, `SHOW USER PRIVILEGES` will only work in a limited capacity; -It is only possible for a user to show their own privileges. +Note that if a non-native auth provider like LDAP is in use, `SHOW USER PRIVILEGES` will only work with a limited capacity as it is only possible for a user to show their own privileges. Other users' privileges cannot be listed when using a non-native auth provider. ==== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USER[S] [name[, ...]] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] [WHERE expression] @@ -1123,7 +1111,7 @@ SHOW USER[S] [name[, ...]] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ---- -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USER jake PRIVILEGES ---- @@ -1176,7 +1164,7 @@ Lists all privileges for user `jake`. 7+a|Rows: 4 |=== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USERS jake, joe PRIVILEGES ---- @@ -1262,22 +1250,22 @@ Lists all privileges for users `jake` and `joe`. |=== The same command can be used at all times to review available privileges for the current user. -For this purpose, a shorter form of the the command also exists: `SHOW USER PRIVILEGES` +For this purpose, there is a shorter form of the command: `SHOW USER PRIVILEGES`: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USER PRIVILEGES ---- -As for the other privilege commands, available privileges for users can also be output as Cypher commands with the optional `AS COMMAND[S]`. +As for the other privilege commands, available privileges for users can also be listed as Cypher commands with the optional `AS COMMAND[S]`. [NOTE] ==== -When showing _user_ privileges as commands, the roles in the Cypher commands are replaced with a parameter. +When showing user privileges as commands, the roles in the Cypher commands are replaced with a parameter. This can be used to quickly create new roles based on the privileges of specific users. ==== -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USER jake PRIVILEGES AS COMMANDS ---- @@ -1296,7 +1284,7 @@ a|Rows: 4 Like other `SHOW` commands, the output can also be processed using `YIELD` / `WHERE` / `RETURN`. Additionally, similar to the other show privilege commands, it is also possible to show the commands for revoking the privileges. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- SHOW USER jake PRIVILEGES AS REVOKE COMMANDS WHERE command CONTAINS 'EXECUTE' @@ -1312,13 +1300,14 @@ a|Rows: 2 |=== + [role=enterprise-edition] [[access-control-revoke-privileges]] == Revoking privileges Privileges that were granted or denied earlier can be revoked using the `REVOKE` command: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- REVOKE [ GRANT | DENY ] graph-privilege @@ -1327,16 +1316,15 @@ REVOKE An example usage of the `REVOKE` command is given here: -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- REVOKE GRANT TRAVERSE ON HOME GRAPH NODES Post FROM regularUsers ---- -While it can be explicitly specified that revoke should remove a `GRANT` or `DENY`, it is also possible to revoke either one by not specifying at all as the next example demonstrates. -Because of this, if there happen to be a `GRANT` and a `DENY` on the same privilege, it would remove both. +While it can be explicitly specified that `REVOKE` should remove a `GRANT` or `DENY`, it is also possible to `REVOKE` both by not specifying them at all, as the next example demonstrates. +Because of this, if there happens to be a `GRANT` and a `DENY` for the same privilege, it would remove both. -[source, cypher, role=noplay, indent=0] +[source, cypher, role=noplay] ---- REVOKE TRAVERSE ON HOME GRAPH NODES Payments FROM regularUsers ---- - From bf7619a44accf92a9775cd422a1ba5c2f3a84ce5 Mon Sep 17 00:00:00 2001 From: lidiazuin Date: Tue, 26 Jul 2022 13:57:05 +0200 Subject: [PATCH 2/2] update --- modules/ROOT/pages/access-control/manage-privileges.adoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/access-control/manage-privileges.adoc b/modules/ROOT/pages/access-control/manage-privileges.adoc index 6fddf76c2..8c773ed8b 100644 --- a/modules/ROOT/pages/access-control/manage-privileges.adoc +++ b/modules/ROOT/pages/access-control/manage-privileges.adoc @@ -297,7 +297,7 @@ SHOW [ALL] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] SHOW [ALL] PRIVILEGE[S] [AS [REVOKE] COMMAND[S]] YIELD { * | field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n] [WHERE expression] - [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n] + [RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]] ---- [source, cypher, role=noplay] @@ -686,7 +686,8 @@ In this example: [source, cypher, role=noplay] ---- -SHOW PRIVILEGES WHERE graph <> '*' +SHOW PRIVILEGES +WHERE graph <> '*' ---- In this example, the `WHERE` clause is used to filter privileges down to those that target specific graphs only. @@ -730,7 +731,7 @@ In this case, by user and `GRANTED` or `DENIED`: [source, cypher, role=noplay] ---- -SHOW PRIVILEGES YIELD * RETURN role, access, collect([graph, resource, segment, action]) as privileges +SHOW PRIVILEGES YIELD * RETURN role, access, collect([graph, resource, segment, action]) AS privileges ---- .Result