diff --git a/modules/user-access/pages/access-control-model.adoc b/modules/user-access/pages/access-control-model.adoc index bc4a75ee..c01bd5ed 100644 --- a/modules/user-access/pages/access-control-model.adoc +++ b/modules/user-access/pages/access-control-model.adoc @@ -61,6 +61,10 @@ They do not need to have privileges specifically for those graphs, types, or att Data CRUD privileges (`CREATE_DATA`, `READ_DATA`, `UPDATE_DATA`, `DELETE_DATA`) are special in that they can be granted on the type level and attribute level. +To grant type-level privileges to a role, see xref:user-access:role-management.adoc#_grant_type_level_privilege_to_a_role[Grant type-level privilege to a role]. + +To grant attribute-level privileges to a role, see xref:user-access:role-management.adoc#_grant_attribute_level_privilege_to_a_role[Grant attribute-level privilege to a role]. + NOTE: Data CRUD privileges only govern data access through queries and REST endpoints. Users with the `EXECUTE_LOADINGJOB` privilege do not need additional privileges in order to run a loading job that inserts or deletes vertices and edges. diff --git a/modules/user-access/pages/role-management.adoc b/modules/user-access/pages/role-management.adoc index 7fddef91..c27cd8db 100644 --- a/modules/user-access/pages/role-management.adoc +++ b/modules/user-access/pages/role-management.adoc @@ -236,6 +236,52 @@ GRANT READ, CREATE ON VERTEX Person IN GRAPH G1 TO role1, role2 This allows users with `role1` and `role2` to read all attribute values of type `Person` vertices. However, to insert new vertices, the user must also have `UPDATE_DATA` on all attributes of vertex type `Person`. +=== Type-level access control example + +Consider the following schema and a user account called `user1`: + +[source,gsql] +---- +CREATE VERTEX person(id UINT PRIMARY KEY, name STRING) +CREATE VERTEX city(id UINT PRIMARY KEY, name STRING) +CREATE GRAPH G1(person, city) +---- + +To run the query below, `user1` needs `READ_DATA` privilege on vertex type `city`, +because `PRINT Seed` outputs all details for that type. + +[source,gsql] +---- +USE GRAPH G1 +CREATE QUERY q1() FOR GRAPH G1 { + Seed = {city.*}; + PRINT Seed; +} +---- + +Without the privilege, running this query returns the following error: + +[source,console] +---- +User 'user1' does not have the permission to run the command +Required Data Privileges: + - Graph 'G1' Privileges: + - Type 'city' Privileges: + READ_DATA [MISSING] +Please rewrite the query, or ask for the [MISSING] privileges +---- + +To fix this, create a role with `READ_DATA` on vertex type `city` in graph `G1` and grant it to `user1`: + +[source,gsql] +---- +CREATE ROLE role1 ON GLOBAL +GRANT READ ON VERTEX city IN GRAPH G1 TO role1 +GRANT ROLE role1 TO user1 +---- + +`user1` can now run `q1` successfully. + == Grant attribute-level privilege to a role You can grant certain privileges (`READ_DATA`, `CREATE_DATA`, `UPDATE_DATA`) on an attribute level to a role. @@ -262,6 +308,51 @@ GRANT READ ON VERTEX person ATTRIBUTE id, age IN GRAPH G1 TO example_role This allows users with `example_role` to read the `id` and `age` attribute values of `Person` vertices. However, if the type `Person` has other attributes, such as an `SSN` attribute with their social security number, users who don't have the `READ_DATA` privilege on that attribute are not able to access its attribute value. +=== Attribute-level access control example + +To run the query below, `user1` needs `READ_DATA` privilege on the attribute `name` and its primary key `id` of vertex type `person` in graph `G1`. + +* The privilege on `id` is required because the primary key is needed to traverse the type. +* The privilege on `name` is required because the attribute `name` is added into the global SetAccum `@@personNames`. + +[source,gsql] +---- +USE GRAPH G1 +CREATE QUERY q2() FOR GRAPH G1 { + SetAccum @@personNames; + vSet = SELECT s FROM person:s + POST-ACCUM + @@personNames += s.name; + PRINT @@personNames; +} +---- + +Without the privilege, running this query returns the following error: + +[source,console] +---- +User 'user1' does not have the permission to run the command +Required Data Privileges: + - Graph 'G1' Privileges: + - Type 'person' Privileges: + - Attribute 'id' Privileges: + READ_DATA [MISSING] + - Attribute 'name' Privileges: + READ_DATA [MISSING] +Please rewrite the query, or ask for the [MISSING] privileges +---- + +To fix this, create a role with `READ_DATA` on attributes `id` and `name` of vertex type `person` in graph `G1` and grant it to `user1`: + +[source,gsql] +---- +CREATE ROLE role2 ON GLOBAL +GRANT READ ON VERTEX city ATTRIBUTE id, name IN GRAPH G1 TO role2 +GRANT ROLE role2 TO user1 +---- + +`user1` can now run `q2` successfully. + The following command grants the `READ_DATA` privilege on the `to` attribute of the edge type `Knows` to `example_role`: [source.wrap,gsql]