---
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: "4.1"
module: "user-access"
html_url: "/tigergraph-server/4.1/user-access/role-management"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.1/user-access/role-management"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.1/user-access/role-management.md"
---

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

# Role Management

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

> [!NOTE]
> **Known Issue**: usernames beginning with a digit or containing non-alphanumeric characters cannot grant or revoke privileges.

For Row Policy and Object-Based privilege management, see[RBAC Row Policy Overview](https://www.tigergraph.com/docs/tigergraph-server/4.1/user-access/rbac-row-policy/row-policy-overview.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.

Both `SHOW GRANTS TO ROLE` and `SHOW PRVILEGE ON ROLE` shows 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
```

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

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

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

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

> [!NOTE]
> **Known Issue**: usernames beginning with a digit or containing non-alphanumeric characters cannot grant or revoke privileges.

### Syntax

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

### Required privilege

`WRITE_ROLE`

### Example

1. To grant privileges to a role, run the Object-based grant privilege command from the GSQL shell:  
```text  
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`. For more information on query privileges, see [Fine-Grained Query Privileges](https://www.tigergraph.com/docs/tigergraph-server/4.1/user-access/fine-grained-query-privileges.md).

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

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

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

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

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

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

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

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

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

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

```gsql
REVOKE CREATE, UPDATE ON EDGE Friendship ATTRIBUTE startdata IN GRAPH Social 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.
