Role Management

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

To see role management tasks under the Access Control List (ACL) model, see Access Control Lists (ACLs).

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

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

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.

SHOW GRANTS TO ROLE shows both the RBAC and ACL privileges of a role. SHOW PRVILEGE ON ROLE shows only 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

ACL privileges of Role: "moderator"
No ACL privileges.

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

GSQL > SHOW PRIVILEGE ON ROLE role1 , role2

To view the ACL privileges of a role, see View ACL privileges of a role.

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

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.
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 <privilege_name1> (, privilege_name2)*
        [ON GRAPH <graph_name>] TO <role_name1> (, <role_name2>)*

Require privilege

WRITE_ROLE

Example

To grant privileges to a role, run the GRANT PRIVILEGE command from the GSQL shell:

GSQL > GRANT PRIVILEGE WRITE_QUERY, WRITE_ROLE
        ON GRAPH example_graph TO role1 , role2

This will allow users with the roles role1 and role2 to edit and install 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 Privileges.

To grant ACL privileges to a role, see Grant ACL privileges to a role.

Grant type-level privilege 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 privilege_name1 , privilege_name2... ON VERTEX/EDGE <graph_name>.<type.name>  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 role2 and role2.

GRANT PRIVILEGE READ_DATA, CREATE_DATA ON VERTEX G1.Person 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, WRITE_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 privilege_name1 , privilege_name2... ON VERTEX/EDGE <graph_name>.<type.name> (<attribute1>, <attribute2> ...) 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 PRIVILEGE READ_DATA ON VERTEX G1.person (id, age) 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 PRIVILEGE READ_DATA ON edge ldbc_snb.Knows(to) 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 <privilege_name1> (, privilege_name2)*
        [ON GRAPH <graph_name>] FROM <role_name1> (, <role_name2>)*

Required privilege

WRITE_ROLE

Example

To revoke privileges from a role, run the REVOKE PRIVILEGE command from the GSQL shell:
```
GSQL > REVOKE PRIVILEGE WRITE_QUERY
        ON GRAPH example_graph FROM role1
```

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

To revoke ACL privileges from a role, see Revoke ACL privileges from a role.

Revoke type-level privileges

You can revoke certain privileges from the type level with the REVOKE PRIVILEGE command.

If the privilege has already been granted on the global scope or on the graph level, then revoking the privilege on the type level does not revoke the privilege in effect.

Syntax

REVOKE PRIVILEGE <privilege_name1>, <privilege_name2> ... ON VERTEX/EDGE <graph_name>.<type.name> FROM <role_name> , <role_name2>...

Required privilege

WRITE_ROLE

Example

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

REVOKE PRIVILEGE UPDATE_DATA ON EDGE Social.Friendship FROM role1, role2

Revoke attribute-level privileges

You can revoke certain privileges from the attribute level with the REVOKE PRIVILEGE command.

If the privilege has already been granted on the global scope, on the graph level, or type level, then revoking the privilege on the type level does not revoke the privilege in effect.

Syntax

REVOKE PRIVILEGE privilege_name1 , privilege_name2... ON VERTEX/EDGE <graph_name>.<type.name> (<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 PRIVILEGE CREATE_DATA, UPDATE_DATA ON EDGE Social.Friendship (startdata) FROM role1, role2

Drop a role

Syntax

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

Required privilege

WRITE_ROLE

Example

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.