Role Management

This page explains the procedures for various role management tasks under TigerGraph’s role-based access control model.

For Row Policy and Object-Based privilege EBNF examples see RBAC Row Policy EBNF.

Create a local role

Local roles are deprecated and will be dropped in a future release.

Syntax

CREATE ROLE <role_name> (, <role_name>)* [ON GRAPH <graph_name>]

Required privilege

WRITE_ROLE

Example

  1. To create a local role, run the CREATE ROLE command like below. If you choose not to specify a graph in the command, the current scope will be used as the scope of the role:

    GSQL > USE GRAPH example_graph
GSQL > CREATE ROLE role1, role2

This will create two roles named role1 and role2 on graph example_graph. By default, these two roles do not have any privilege:

Successfully created local roles for graph 'example_graph': [role1, role2].

Create a global role

You can create a global role with the CREATE ROLE command.

Syntax

CREATE ROLE <role_name> (, <role_name>)* ON GLOBAL

Required privilege

WRITE_ROLE on the global scope

Example

  1. To create a global role, run the CREATE ROLE command like below. Replace role1 with the name of the role you are creating.

CREATE ROLE role1 ON GLOBAL

This will create a role named role1 on the global scope. By default, this role has no privileges:

Successfully created global roles: [role1].

View privileges of a role

Users with the READ_ROLE privilege in a scope can view the privileges on the roles in that scope.

Both SHOW GRANTS TO ROLE and SHOW PRVILEGE ON ROLE shows the RBAC privileges of a role.

Syntax

SHOW PRIVILEGE ON ROLE <role_name>, <role_name2> ...
SHOW GRANTS TO ROLE <role_name1>, <role_name2> ...

Required privilege

READ_ROLE on the global scope

Example

The following command shows all privileges of the role moderator:

GSQL > USE GLOBAL
GSQL > SHOW GRANTS TO ROLE moderator
RBAC privileges of Role: "moderator"
- Global Privileges:
READ_DATA
- Graph 'Social' Privileges:
- Type 'Person' Privileges:
CREATE_DATA
- Attribute 'locationIP' Privileges:
UPDATE_DATA

The following command shows all privileges of the roles role1 and role2:

GSQL > SHOW PRIVILEGE ON ROLE role1 , role2

View all users who are assigned a role

You can specify a role and view all users who are assigned that role.

Syntax

SHOW GRANTS OF ROLE <role_name1>, <role_name2> ...

Require privilege

READ_ROLE and READ_USER on global scope

Example

The following command shows all users with the role moderator:

GSQL > SHOW GRANTS OF ROLE moderator
Users with role moderator:
  tigergraph

List all existing roles

Syntax

SHOW ROLE

Required privilege

READ_ROLE

Example

  1. To list all existing roles, first ensure that you are in the correct scope. Run USE <graph_name> or USE GLOBAL to switch to your desired scope.

  2. Run the SHOW ROLE command:

    GSQL > SHOW ROLE

This will show all the roles in your current scope:

  - Builtin Roles:
    observer
    queryreader
    querywriter
    designer
    admin
    globaldesigner
    superuser

  - User Defined Roles:
    - Graph 'tpc_graph' Roles:
      role1
      role2

Grant privileges to a role

Users with the WRITE_ROLE privileges on a scope can grant RBAC privileges to the roles in that scope.

Syntax

GRANT <privilege_name1> (, <privilege_name2>)*
ON (GLOBAL | ALL <object_type_plural1> (, ALL <object_type_plural2>)* | <object_type> <object_name1> ((, <object_name2>)* | <attribute_type> <attribute_name1> (, <attribute_name2>)*)?)
IN [GRAPH <graph_name>|GLOBAL] TO <role_name1> (, <role_name2>)*

Require privilege

WRITE_ROLE

Example

  1. To grant privileges to a role, run the Object-based grant privilege command from the GSQL shell:

    GSQL > GRANT WRITE ON ALL QUERIES, ALL ROLES
        IN GRAPH example_graph TO role1 , role2

This will allow users with the roles role1 and role2 to create, read, update, drop, install and execute existing queries, as well as modify roles on the graph example_graph. To see a full list of privileges and the command they allow users to run, see List of Legacy Privilege Syntax.

Grant type-level privilege to a role

You can grant certain privileges (READ_DATA, CREATE_DATA, DELETE_DATA, UPDATE_DATA) on a type level to the roles in that scope. The privilege only applies to the specified types.

Syntax

GRANT <privilege_name1> (, <privilege_name2>)* ON [VERTEX|EDGE] <type_name1> (, <type_name2>)* IN [GRAPH <graph_name>|GLOBAL] TO <role_name> (, <role_name2>)*

Required privilege

WRITE_ROLE and the privilege being granted

Example

The following command grants the READ_DATA and CREATE_DATA privilege on vertex type Person to role1 and role2.

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.

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. The privilege only applies to the specified attributes of the specified type.

Syntax

GRANT <privilege_name1> (, <privilege_name2>)* ON [VERTEX|EDGE] <type_name> ATTRIBUTE <attribute_name1> (, <attribute_name2>)* IN [GRAPH <graph_name>|GLOBAL] TO <role_name> (, <role_name2>)*

from and to are edge attributes that represent the source vertex and target vertex of an edge. When you grant access to these attributes, from and to are case-sensitive. You must use lower-case to indicate these two attributes.

Required privilege

WRITE_ROLE and the privilege being granted

Example

The following command grants the READ_DATA privilege on the id and age attribute of the vertex type Person to example_role.

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.

The following command grants the READ_DATA privilege on the to attribute of the edge type Knows to example_role:

GRANT READ ON EDGE Knows ATTRIBUTE to IN GRAPH ldbc_snb TO example_role (1)
1 to must be lower-case.

Revoke privileges from a role

Users with the WRITE_ROLE privileges on a scope can revoke RBAC privileges from the roles in that scope.

Syntax

REVOKE <privilege_name1> (, <privilege_name2>)*
ON (GLOBAL | ALL <object_type_plural1> (, ALL <object_type_plural2>)* | <object_type> <object_name1> ((, <object_name2>)* | <attribute_type> <attribute_name1> (, <attribute_name2>)*)?)
IN [GRAPH <graph_name> | GLOBAL]
FROM <role_name1> (, <role_name2>)*

Required privilege

WRITE_ROLE

Example

  1. To revoke privileges from a role, run the Object-based revoke privilege command from the GSQL shell:

    GSQL > REVOKE WRITE ON ALL SCHEMA
        IN GRAPH example_graph FROM role1

This will revoke the WRITE_SCHEMA privilege from the role role1 on graph example_graph.

Revoke type-level privileges

You can revoke certain privileges from the type level with the Object-based revoke privilege command.

Revoking a privilege at the type does not affect privileges granted at higher levels (e.g., global or graph level). For instance, if a role has READ_DATA` on a vertex type globally, revoking this privilege at the type level will not prevent the role from accessing the vertex type.

Syntax

REVOKE <privilege_name1> (, <privilege_name2>)* ON [VERTEX|EDGE] <type_name> (, <type_name2>)* IN [GRAPH <graph_name>|GLOBAL] FROM <role_name> (, <role_name2>)*

Required privilege

WRITE_ROLE

Example

The following command revokes the UPDATE_DATA privilege on type Friendship from role1, and role2:

REVOKE UPDATE ON EDGE Friendship IN GRAPH Social FROM role1, role2

Revoke attribute-level privileges

You can revoke certain privileges from the attribute level with the Object-based revoke privilege command.

Revoking a privilege at the type does not affect privileges granted at higher levels (e.g., global, graph level or type level). For instance, if a role has READ_DATA` on a vertex type globally, revoking this privilege at the attribute level will not prevent the role from accessing the vertex attribute type.

Syntax

REVOKE <privilege_name1> (, privilege_name2)* ON [VERTEX|EDGE] <type_name> ATTRIBUTE <attribute1> (, <attribute2>)* FROM <role_name> (, <role_name2>)*

Required privilege

WRITE_ROLE and the privilege being granted

Example

The following command revokes CREATE_DATA and UPDATE_DATA on the startdata attribute from role1 and role2.

If the user doesn’t have these privileges, they are not able to create new edges of type Friendship.

REVOKE CREATE, UPDATE ON EDGE Friendship ATTRIBUTE startdata IN GRAPH Social FROM role1, role2

Drop a role

Syntax

DROP ROLE <role_name> (, <role_name2>)*

Required privilege

WRITE_ROLE

Example

  1. To drop a role, run the DROP ROLE command from the GSQL shell:

    GSQL > DROP ROLE role1 , role2

This will drop the roles role1 and role2. This will also revoke the roles from users who have been granted these roles.