Access Control Lists (ACLs)

Access Control Lists (ACLs) allow you finer-grained control over access to queries. Using GSQL commands, you can change the owner of a query, grant ACL privileges on a query to a role, and view the ACL privileges on a user, a role, or a query.

Modify ACL passwords

Set ACL password

By default, users don’t have ACL passwords. They can choose to set an ACL password. Once a user’s ACL password is set, changing the ACL of queries owned by the user requires entering the user’s ACL password.

Syntax

  • Interactive

  • Non-interactive

ALTER [USER <username>] ACL PASSWORD

This will prompt you to enter your ACL password.

ALTER [USER <username>] ACL PASSWORD SET <new_acl_password>

Required privilege

  • None if a user is setting their own ACL password

  • WRITE_USER if a user is setting the ACL password of another user

Procedure

  • Change password of current user

  • Change password of another user

To change the password of the current user, run the following command:

GSQL > ALTER ACL PASSWORD SET "example_Password" (1)
1 Putting the password in double quotes allow you to use special characters. You can enter a password without the double quotes, in which case you are only able to use alphanumerical characters.

To change the ACL password of another user, run the following command and replace user1 with the user whose ACL password you want to change:

GSQL > ALTER USER user1 ACL PASSWORD SET examplePassword (1)
1 Since the password isn’t enclosed in double quotes, only alphanumerical characters are allowed.

Change ACL password

To change the ACL password of a user whose password has already been set, you need to enter their current ACL password.

Syntax

ALTER [USER <username>] ACL PASSWORD SET <new_acl_password> REPLACE <current_acl_password>

Required privilege

  • None if a user is changing their own ACL password.

  • WRITE_USER for changing the ACL password of another user.

In both scenarios, changing ACL password requires the current password.

Procedure

  • Change password of current user

  • Change password of another user

To change the password of the current user, run the following command and replace "current_password" with the current password of the user:

GSQL > ALTER ACL PASSWORD SET "new_password" REPLACE "current_password" (1)
1 Putting the password in double quotes allow you to use special characters. You can enter a password without the double quotes, in which case you are only able to use alphanumerical characters.

To change the password of another user, run the following command and replace "current_password" with the current password of the user:

GSQL > ALTER USER user1 ACL PASSWORD SET newPassword REPLACE currentPassword (1)
1 Since the password isn’t enclosed in double quotes, only alphanumerical characters are allowed.

Delete ACL password

Users can delete their own ACL password or another user’s ACL password if they have the sufficient privilege and the current ACL password.

Syntax

ALTER [USER <username>] ACL PASSWORD CLEAR REPLACE <current_acl_password>

Required privilege

  • None if a user is deleting their own ACL password.

  • WRITE_USER for deleting the ACL password of another user.

In both scenarios, deleting ACL password requires the current password.

Procedure

  • Deleting password of current user

  • Deleting password of another user

To delete the ACL password of the current user, run the following command and replace "current_password" with the current password of the user:

GSQL > ALTER ACL PASSWORD CLEAR REPLACE "current_password"

To delete the ACL password of another user, run the following command and replace "current_password" with the current password of the user:

GSQL > ALTER USER user1 ACL PASSWORD CLEAR REPLACE "current_password"

Modify ACL privileges

Change query owner

With the ACL password of the current query owner, the owner themself or users with the WRITE ROLE privilege can change the owner of a query. If the current owner of the query doesn’t have an ACL password, then changing the owner does not require a password.

If a query does not have a current owner due to upgrades from an older version of TigerGraph, then anyone with the WRITE_ROLE privilege can run the command to change the query owner.

Syntax

CHANGE OWNER OF QUERY <query_name> TO <username> [SECURED BY <acl_password>] (1)
1 If current ACL password is not supplied in the command, GSQL prompts the user for the ACL password if the query owner has an ACL password.

Required privilege

  • None if the query is owned by the current user

  • WRITE_ROLE if the query is owned by another user

Procedure

To change the owner of a query, run the following command and replace owner_password with the ACL password of the query owner.

GSQL > CHANGE OWNER OF QUERY my_query TO user1 SECURED BY "owner_acl_password"

Grant ACL privilege to a role

The owner and only the owner of a query can grant ACL privileges on the query to specified roles. To grant an ACL privilege, the query owner must themselves have the corresponding RBAC privilege.

Syntax

GRANT ACL PRIVILEGE ( READ | EXECUTE ) ON QUERY <query_name> TO <role1> (, <role2> ...)* [SECURED BY <owner_acl_password>] (1)
1 If current ACL password is not supplied in the command, GSQL prompts the user for the ACL password if the query owner has an ACL password.

Required privilege

  • READ_QUERY for granting READ privilege on the query.

  • READ_DATA for granting EXECUTE privilege on queries that do not update the graph.

  • READ_DATA and appropriate CRUD privileges for granting EXECUTE privilege on queries that create, update, or delete data of the graph.

    • For queries that update existing vertices and edges, the UPDATE_DATA privilege is needed.

    • For queries that delete vertices or edges, the DELETE_DATA privilege is needed.

    • For queries that create vertices or edges, the ACL privilege situation can be more complicated. See Data CRUD privileges.

Procedure

To grant READ privilege for a query example_query to a role example_role, run the following command. To grant EXECUTE privilege instead, replace READ with EXECUTE:

GSQL > GRANT ACL PRIVILEGE READ ON QUERY example_query TO example_role

Revoke ACL privilege from a role

The owner of a query can revoke ACL privileges on the query from a role. If the ACL entry for a privilege (either READ or EXECUTE) becomes empty after removing specified roles, the entry status for the privilege becomes NOBODY. When the ACL entry status for a privilege is NOBODY, no one, including the query owner, can access the query in the corresponding manner.

The effect of revoking ACL privileges from all roles in an entry by revoking from specified roles is different from revoking ACL privileges from all using the keyword ALL.

Syntax

REVOKE ACL PRIVILEGE ( READ | EXECUTE ) ON QUERY <query_name> FROM <role1> (, <role2>, ... )* [SECURED BY <owner_acl_password>] (1)
1 If current ACL password is not supplied in the command, GSQL prompts the user for the ACL password if the query owner has an ACL password.

Required privilege

None. Only query owner can run the command. If the query owner set their ACL password, running the command requires entering the ACL password.

Procedure

To revoke ACL READ privilege on example_query from role1, run the following command and replace owner_acl_password with the ACL password of the owner. If you want to remove EXECUTE privilege, replace READ with EXECUTE.

GSQL > REVOKE ACL PRIVILEGE READ ON QUERY example_query FROM role1 SECURED BY
"owner_acl_password"

Revert access control to RBAC

The owner of a query can choose to revert access control governance of a query to RBAC by changing its ACL entry status to unspecified.

Syntax

REVOKE ACL PRIVILEGE ( READ | EXECUTE ) ON QUERY <query_name> FROM ALL [SECURED BY <owner_acl_password>] (1)
1 If current ACL password is not supplied in the command, GSQL prompts the user for the ACL password if the query owner has an ACL password.

Required privilege

None. Only query owner can run the command. If the query owner set their ACL password, running the command requires entering the ACL password.

Procedure

To revert access control on read operations on example_query to RBAC, run the following command and replace owner_acl_password with the ACL password of the owner. If you want to revert access control for RUN QUERY (EXECUTE privilege), replace READ with EXECUTE.

GSQL > REVOKE ACL PRIVILEGE READ ON QUERY example_query FROM ALL SECURED BY
"owner_acl_password"

Disallow access for all

If the query owner grants a type of ACL privilege on a query to NOBODY, no one will be able to access the query, including the query owner.

Syntax

GRANT ACL PRIVILEGE ( READ | EXECUTE ) ON QUERY <query_name> TO NOBODY [ SECURED BY <owner_acl_password> ] (1)
1 If current ACL password is not supplied in the command, GSQL prompts the user for the ACL password if the query owner has an ACL password.

Required privilege

None. Only query owner can run this command. If the query owner set their ACL password, running the command requires entering the ACL password.

Procedure

To disallow read access to query example_query, run the following command as the query owner. If the query owner set an ACL password, you need to use the SECURED BY option to enter the ACL password.

GSQL > GRANT ACL PRIVILEGE READ ON QUERY example_query TO NOBODY

View ACL privileges

View ACL entries on a query

You can view the entries on a query’s access control list. The ACL shows the owner of the query, as well as which roles can read or execute the query.

Syntax

SHOW ACL PRIVILEGE ON QUERY <query1> (, <query2> ...)*

Required privilege

Procedure

To view the access control list of query1 and query2, run the following command:

GSQL > SHOW ACL PRIVILEGE ON QUERY query1, query2

View ACL privileges of a user

You can view the ACL privileges of a user. This allows you to see the queries owned by the user, as well as the queries that the user has read and execute access to on all graphs where you have the READ_USER privilege.

Syntax

SHOW ACL PRIVILEGE ON USER <user1> (, <user2> ...)*

Required privilege

READ_USER

Procedure

To view the ACL privileges of user1 and user2, run the following command:

GSQL > SHOW ACL PRIVILEGE ON USER user1, user2

View ACL privileges of a role

You can view the ACL privileges of a role. This shows the queries the role has read or execute access to on all graphs where you have the READ_ROLE privilege.

Syntax

SHOW ACL PRIVILEGE ON ROLE <role1> (, <role1> ...)*

Required privilege

READ_ROLE

Procedure

To view the ACL privileges of role role1 and role2, run the following command:

SHOW ACL PRIVILEGE ON ROLE role1, role2