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.
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
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.
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
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.
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
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. |
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 grantingREAD
privilege on the query. -
READ_DATA
for grantingEXECUTE
privilege on queries that do not update the graph. -
READ_DATA
and appropriate CRUD privileges for grantingEXECUTE
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.
-
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 |
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. |
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.
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.