Access Control Model in TigerGraph

TigerGraph supports both role-based access control (RBAC) and access control lists (ACL):

  • RBAC lets you grant access to different actions on all of a certain type of objects on a graph or a type, such as allowing a role to read data on all vertices of a specified type.

  • ACLs are only relevant for governing access to queries, and let you grant access to specific queries.

Role-based access control

TigerGraph uses role-based access control (RBAC) to manage authorization. On every graph, privileges to perform actions are assigned to roles, and roles are granted to users. Outside the permissions granted by their roles, a user has no access to the system.

Privileges

A privilege is permission to perform an action in a given scope. When a privilege is assigned to a role, it allows users with the role to perform the specified action in the specified scope. For example, the privilege READ_SCHEMA on graph Social gives a user read permission to the schema of the graph Social. This allows the user to run commands such as ls and SHOW VERTEX on the graph Social.

To view a complete list of privileges available in TigerGraph and the commands they enable a user to run, see List of Privileges.

Global vs local privileges

The scope of a privilege can be global or local. Global privileges apply to all graphs and global objects. Local privileges only apply on the graph they belong to.

For example, a role with WRITE_QUERY on graph Social can only create queries on graph social, but not on other graphs. In contrast, a role with WRITE_QUERY on the global scope can create queries on all graphs.

Local roles can only be granted local privileges, while global roles can be granted both local and global privileges.

Global-only privileges

Some privileges can only be global by nature. For example, since users are global objects, any user-related privileges are global only. To see which privileges are global-only, see List of Privileges.

Roles

A role is a collection of privileges that are assigned to users to grant them permission to perform actions on specific resources.

Global vs local roles

Roles can be global or local. Local roles can only be granted local privileges, while global roles can be granted both local and global privileges.

For example, if a user creates a role manager on the graph Social:

GSQL > CREATE ROLE manager ON GRAPH Social
Successfully created roles: [manager].

This role can only be granted privileges on the graph Social. It cannot be granted global privileges.

Built-in roles

GSQL offers five built-in local roles and two built-in global roles. The built-in roles cannot be dropped. The following table summarizes the built-in roles and their corresponding set of privileges:

Name Global or Local Privilege List

observer

Local

READ_SCHEMA, READ_LOADINGJOB,READ_QUERY

queryreader

Local

READ_SCHEMA, READ_LOADINGJOB,READ_QUERY, EXECUTE_LOADINGJOB, READ_DATA

querywriter

Local

READ_SCHEMA, READ_LOADINGJOB,READ_QUERY, EXECUTE_LOADINGJOB, READ_DATA, WRITE_QUERY, WRITE_DATA

designer

Local

READ_SCHEMA, READ_LOADINGJOB,READ_QUERY, EXECUTE_LOADINGJOB, READ_DATA, WRITE_QUERY, WRITE_DATA, WRITE_SCHEMA, WRITE_LOADINGJOB, ACCESS_TAG

admin

Local

READ_SCHEMA, READ_LOADINGJOB,READ_QUERY, EXECUTE_LOADINGJOB, READ_DATA, WRITE_QUERY, WRITE_DATA, WRITE_SCHEMA, WRITE_LOADINGJOB, ACCESS_TAG WRITE_ROLE, WRITE_DATASOURCE, READ_ROLE, READ_USER, READ_PROXYGROUP

globaldesigner

Global

Designer’s privileges on the global scope, DROP_GRAPH for graphs created by the same user

superuser

Global

All supported RBAC privileges

User-defined roles

Users can define roles with their own list of privileges they want to grant to the role. To learn how to manage user-defined roles and privileges for the roles, see Role Management.

Access control lists

ACLs give you the ability to apply finer-grained access control to a GSQL query by specifying who can read or execute the query. ACLs are bound to queries.

Each query has two ACLs - a read list and an execute list - for read privilege and execute (run) privilege on a given query, respectively. Each list consists of a set of roles. Users with roles on the ACLs of a query have the permission to either read or execute the query.

ACL status

ACLs of a query have three statuses:

Unspecified

Default status. When an ACL is unspecified, RBAC governs the access for that privilege.

Specified Roles

Only the users with specified roles have the ACL privilege. Any roles (local/global, built-in/user-defined) can be added to an ACL.

Nobody

No one, not even the owner of the query, can access the query, even with the corresponding RBAC privileges.

Query owner

Every query has one and only one owner. Only the owner of a query can:

  • run ACL management commands to modify the ACLs of query.

  • run CREATE OR REPLACE to update a query. When the query owner runs CREATE OR REPLACE to update a query, the ACLs on the query remains unchanged.

When a query is created, the creator of the query is assigned to be the owner automatically. When a user is the owner of a query, the user cannot be dropped unless the query is dropped or if the owner of the query is changed.

When you upgrade from a version prior to 3.4, the old queries have no owner. Users with WRITE_ROLE privilege on the graph or on the global scope can assign an owner to a query without owners.

ACL password

Users have the option of setting an ACL password. When a user has an ACL password, operations that modify ACL privileges of queries owned by that user require their ACL password. These operations include:

  • Changing the owner of a query

  • Modifying the ACL privileges on a query

Examples

Using NOBODY ACL status to hide query from everyone

In the following example, user1 protects their query q1 from being seen by anyone, including users with the superuser roles, by setting the status of the READ list of their query’s ACL to NOBODY.

Even though no one can see the content of the query, but since the EXECUTE entry is unspecified, users with sufficient RBAC privileges can still execute the query. This allows user1 to protect the content of a sensitive query, but still allow people to run it.

The following GSQL command are performed by user1:

GSQL > GRANT ACL PRIVILEGE READ ON QUERY q1 TO NOBODY (1)
[WARNING] The READ privileges on the query q1 are denied for any user.
Successfully granted READ on query q1 in the graph ldbc_snb to roles: <NOBODY>.
GSQL > SHOW ACL PRIVILEGE ON QUERY q1 (2)
Query: "q1"
    - Owner:   user1
    - READ:    <Nobody> (2)
    - EXECUTE: <Unspecified>
GSQL > SHOW QUERY q1
CREATE QUERY q1 () {
  /******* Query Content is Hidden. Require ACL privilege READ *******/ (3)
}
GSQL > ALTER ACL PASSWORD SET XXXXXX (4)
1 This command forbids anyone to read the query, even the owner. See ACL status: NOBODY.
2 Use the SHOW ACL PRIVILEGE ON QUERY command to verify the NOBODY status of the READ list.
3 Query content cannot be seen by any user, including the owner.
4 If user user1 does not have an ACL password, it is important to set one. Otherwise, other users with the WRITE_ROLE privilege can change the owner of the query.

Granting and revoking EXECUTE Privilege

In this example, the superuser tigergraph grants and revokes EXECUTE privilege for query q1 for roles role1 and admin.

User user1 is first granted the privilege while user2 is not, then the privilege is revoked from all users.

GSQL > CREATE ROLE role1 ON GRAPH G1
Successfully created local roles on graph 'G1': [role1].
GSQL > GRANT ACL PRIVILEGE EXECUTE ON QUERY q1 TO role1, admin SECURED BY "example_password"
Successfully granted EXECUTE on query q1 in the graph ldbc_snb to roles: [role1, admin].
GSQL > SHOW ACL PRIVILEGE ON ROLE role1, admin
Role: "role1"
- QUERY:
  - EXECUTE:
    - Graph 'G1': [q1]
Role: "admin"
- QUERY:
  - EXECUTE:
    - Graph 'G1': [q1]
GSQL > GRANT ROLE role1 ON GRAPH G1 TO user1
GSQL > SHOW ACL PRIVILEGE ON USER user1
User: "user1"
- QUERY:
  - EXECUTE:
    - Graph 'G1': [q1]

If someone logs in as user user2, who doesn’t have the roles role1 or admin, and tries to run the query, their request is denied.

GSQL > INTERPRET QUERY q1()
User 'user2' does not have the permission to run the command. Required ACL privilege EXECUTE on the query q1.

Log back in as the owner of the query, you can set ACL entries in the query to status unspecified. This disables ACL access control and revert access control to RBAC.

GSQL > REVOKE ACL PRIVILEGE EXECUTE ON QUERY q1 FROM ALL SECURED BY XXXXXX
GSQL > SHOW ACL PRIVILEGE ON USER user1
User: "user1"

How permissions are evaluated

All operations that don’t involve queries are only governed by RBAC. ACLs only apply to queries.

When it comes to evaluating permissions for operations on queries, ACLs are evaluated first:

  • When an ACL is unspecified, RBAC governs the access of the resource. By default, both ACLs (READ and EXECUTE) for a query are unspecified.

  • If the ACL entry is specified, ACL replaces RBAC to govern access for the query.

    • Even if a user does not have the READ_QUERY permission on a graph, they can read a query if they are on the READ list of the query.

    • Even if a user has the READ_QUERY permission on a graph, they cannot read a query if the READ list for the query is specified and the user is not on the list.

Visualization of the hierarchy of permission evaluation for a query evaluation.
Figure 1. How permission is evaluated for a query operation

Importing and exporting

When exporting graphs, ACLs are only exported when both queries and users are exported.

  • When you export graphs without queries, there is no ACL on the exported graphs because there are no queries.

  • When you export graphs with queries but without users, the ACL entries on the exported are reset to the unspecified status.