---
title: "Role Management"
description: "This page explains the procedures for various role management tasks under TigerGraph's role-based access control model."
component: "tigergraph-server"
version: "3.11"
module: "user-access"
html_url: "/tigergraph-server/3.11/user-access/role-management"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/role-management"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/role-management.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/role-management)

# 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)](https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/acl-management.md).

> [!NOTE]
> For Row Policy and Object-Based privilege EBNF examples see [RBAC Row Policy EBNF](https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/rbac-row-policy/row-policy-ebnf.md).

## Create a local role

> [!NOTE]
> Local roles are deprecated and will be dropped in a future release.

### Syntax

```gsql
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  
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

```gsql
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.

```gsql
CREATE ROLE role1 ON GLOBAL
```

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

```console
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

```gsql
SHOW PRIVILEGE ON ROLE <role_name>, <role_name2> ...
```

```gsql
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`:

```text
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
GSQL > SHOW PRIVILEGE ON ROLE role1 , role2
```

To view the ACL privileges of a role, see [View ACL privileges of a role](https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/acl-management.md#_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

```gsql
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
GSQL > SHOW GRANTS OF ROLE moderator
Users with role moderator:
  tigergraph
```

## List all existing roles

### Syntax

```gsql
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  
GSQL > SHOW ROLE  
```

This will show all the roles in your current scope:

```text
  - 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

```text
GRANT PRIVILEGE <privilege_name1> (, privilege_name2)*
        [ON GRAPH <graph_name>] TO <role_name1> (, <role_name2>)*
```

### Require privilege

`WRITE_ROLE`

### Example

1. To grant privileges to a role, run the `GRANT PRIVILEGE` command from the GSQL shell:  
```text  
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, see the [Object-Based Privilege Tables](https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/rbac-row-policy/row-policy-privileges-table.md).

To grant [ACL privileges](https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/access-control-model.md#_access_control_lists) to a role, see [Grant ACL privileges to a role](https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/acl-management.md#_grant_acl_privilege_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

```gsql
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`.

```gsql
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`.

### Type-level access control example

Consider the following schema and a user account called `user1`:

```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.

```gsql
USE GRAPH G1
CREATE QUERY q1() FOR GRAPH G1 {
  Seed = {city.*};
  PRINT Seed;
}
```

Without the privilege, running this query returns the following error:

```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`:

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

### Syntax

```gsql
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`.

```gsql
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.

### 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`.

```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:

```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`:

```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`:

```gsql
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

```text
REVOKE PRIVILEGE <privilege_name1> (, privilege_name2)*
        [ON GRAPH <graph_name>] FROM <role_name1> (, <role_name2>)*
```

### Required privilege

`WRITE_ROLE`

### Example

1. To revoke privileges from a role, run the `REVOKE PRIVILEGE` command from the GSQL shell:  
```text  
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](https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/access-control-model.md#_access_control_lists) from a role, see [Revoke ACL privileges from a role](https://www.tigergraph.com/docs/tigergraph-server/3.11/user-access/acl-management.md#_revoke_acl_privilege_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

```gsql
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`:

```gsql
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

```gsql
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`.

```gsql
REVOKE PRIVILEGE CREATE_DATA, UPDATE_DATA ON EDGE Social.Friendship (startdata) FROM role1, role2
```

## Drop a role

### Syntax

```text
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:  
```text  
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.
