DOC-1730 Add rbac Examples

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.
 

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<STRING> @@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]