MaxCompute provides the ACL-based access control method. You can use this method to grant permissions on an object to a user or role to allow one or more specified actions on an object. ACL is short for access control list. This topic describes the syntaxes of commands that you can use to perform ACL-based access control. This topic also provides examples on how to perform ACL-based access control.

Background information

The ACL-based access control method is implemented based on the whitelist mechanism. The whitelist mechanism allows one or more specified actions on an object for a user or role. The ACL-based access control method is easy-to-use and helps implement precise access control.

After a MaxCompute project is created, ACL-based access control is enabled for the project by default. The owner of a MaxCompute project can run the set CheckPermissionUsingACL=true; or set CheckPermissionUsingACL=false; command to enable or disable ACL-based access control for the project.

The following table describes the use scenarios of the ACL-based access control method.
Operation Description Assigned by Operation platform
Grant permissions to a single user You can grant permissions on an object to a single user to allow one or more specified actions on the object. For more information about the identities that can be used to perform ACL-based access control, see the Authorized by column in the Permission list section in Permission list.
Use a role to grant permissions to multiple users You can grant permissions on an object to a role to allow one or more specified actions on the object. Then, you can assign the role to multiple users. This way, the users are granted the permissions of the role.

For more information about how to create a role and assign a role to a user, see Role planning and management and Assign a role to a user.

Note Roles are used to better manage users. In most cases, roles are granted different permissions on different objects.

Prerequisites

Before you use the ACL-based access control method, make sure that the following conditions are met:
  • The account of the user to which you want to grant permissions or the name of the role to which you want to grant permissions is obtained. The role or account is added to your MaxCompute project. If the account of the user is an Alibaba Cloud account, record the Alibaba Cloud account in the format of ALIYUN$Alibaba Cloud account. If the account of the user is a RAM user, record the RAM user in the format of RAM$Alibaba Cloud account to which the RAM user belongs:Name of the RAM user.

    You can run the list users; or list roles; command on the MaxCompute client to query the account or role name.

    If you want to add a user or role, see User planning and management or Role planning and management.

  • The type of the object on which you want to grant permissions, the name of the object, and the actions that you want to allow on the object are obtained.

    For more information about object types and actions supported for each type of object, see Permissions.

Limits

Before you use the ACL-based access control method, take note of the following limits:
  • You can use the ACL-based access control method to grant the permissions only on an existing object and to an existing subject. If you delete an object and then create an object with the same name, the new object does not inherit the permissions on the deleted object.
  • The ACL-based access control method does not support authorization by using the [with grant option] clause. For example, if User A authorizes User B to access an object, User B cannot authorize User C to access the same object.
  • The ACL-based access control method is implemented based only on the whitelist mechanism. You cannot use this method to deny actions on objects.

Precautions

Before you use the ACL-based access control method, take note of the following items:
  • If you delete an object, MaxCompute revokes all permissions on the object that are granted by using the ACL-based access control method.
  • After a user is removed, the permissions that are granted to the user are retained. If the user is added to the project again, the historical access permissions of the user are activated again. For more information about how to clear the residual permission information of a removed user, see Completely clear the residual permission information of a removed user.

Syntaxes of commands

The following code provides the syntaxes of the commands that you can use to perform ACL-based access control:
  • Grant permissions
    grant <actions> on <object_type> <object_name> 
[(<column_list>)] to <subject_type> <subject_name> 
[privilegeproperties("conditions" = "<conditions>", "expires"="<days>")];
  • Revoke permissions
    revoke <actions> on <object_type> <object_name> 
[(<column_list>)] from <subject_type> <subject_name>;
  • Perform column-level access control
    grant <actions> on table <table_name> (<column_list>) to <subject_type> <subject_name>;
revoke <actions> on table <table_name> (<column_list>) from <subject_type> <subject_name>;
The following table describes the parameters used in the preceding syntaxes.
Parameter Required Description
actions Yes The action that is allowed. You can specify one or more actions in a single command.

If you specify multiple actions, separate them with commas (,). For more information about the supported actions, see Permissions.

object_type Yes The type of the object on which permissions are granted. You can specify only one type of object in a single command.

For more information about the supported object types, see Permissions.

object_name Yes The name of the object on which permissions are granted. The method of obtaining the name of an object varies based on the object type.
  • Project: To obtain the name of a project, log on to the MaxCompute console. In the top navigation bar, select the region where the project resides. On the Project management tab, view the name of the project.
  • Table or view: To obtain the name of a table or view, run the show tables; command on the MaxCompute client.
  • Resource: To obtain the name of a resource, run the list resources; command on the MaxCompute client.
  • Function: To obtain the name of a function, run the list functions; command on the MaxCompute client.
  • Instance: To obtain the name of an instance, run the show instances; command on the MaxCompute client. Instance names are the same as instance IDs in MaxCompute.
You can use asterisks (*) when you configure this parameter. For example, if you set this parameter to table taobao*, all tables whose names start with taobao are matched.
Note You can use asterisks (*) only when the value of subject_type is ROLE.
column_list No The names of columns on which you want to perform access control. This parameter is required only if you set the object_type parameter to Table and you want to perform column-level access control in a table. You can specify one or more column names in a single command. If you specify multiple column names, separate them with commas (,).
Note This parameter is used to specify the specific columns on which you want to manage the Describe, Select, Alter, Update, Drop, and ShowHistory permissions and all permissions. If sensitivity levels are specified for columns in a table, you can use the label-based access control method to manage the access permissions on sensitive data in the columns based on labels for the sensitivity levels.
privilegeproperties conditions No The conditions used for ACL-based access control, such as the source of a request message and the access method. Configure this parameter in the "<var_name> <Operation> Constant" and "<var_name> <Operation> Constant" and ... format. For more information about the valid values of the var_name and Operation parameters, see Conditions in this topic.
days No The duration in which permissions are valid. Unit: days. If you do not configure this parameter, permissions are permanently valid. If you configure this parameter, MaxCompute clears information about the permissions after the duration specified by this parameter elapses.
subject_type Yes The type of the subject to which permissions are granted. Valid values:
  • USER: Alibaba Cloud account or RAM user
  • ROLE: role
subject_name Yes The account of the user to which you want to grant permissions or the name of the role to which you want to grant permissions. You can specify only an account or a role in a single command.

You can run the list users; or list roles; command on the MaxCompute client to query the account or role name.

Conditions

The following table describes the valid values of the var_name and Operation parameters.

var_name Data type Operation Description
acs:UserAgent STRING
  • StringEquals: =
  • StringNotEquals: <>
  • StringLike: like
  • StringNotLike: not like
 The user agent of the client that sent a request.
acs:Referer STRING The HTTP referer of a request.
acs:SourceIp IP Address
  • IpAddress: in (...)
  • NotIpAddress: not in (...)
 The IP address of the client that sent a request.
acs:SecureTransport BOOLEAN
  • True
  • False
 Specifies whether a request is sent over a secure channel, such as an HTTPS channel.
acs:CurrentTime DATEANDTIME
  • DateEquals: =
  • DateNotEquals: <>
  • DateLessThan: <
  • DateLessThanEquals: <=
  • DateGreaterThan: >
  • DateGreaterThanEquals: >=
 The time at which the web server receives a request. The value must follow the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format, such as 2012-11-11T23:59:59Z.

Examples

For example, the Alibaba Cloud account Bob@aliyun.com is the owner of the project test_project_a. Allen, Alice, and Tom are the RAM users of the Alibaba Cloud account Bob@aliyun.com. In the following examples, commands are run on the MaxCompute client.
  • Example 1: Grant permissions to a user
    In this example, a partitioned table named sale_detail is created in the project test_project_a. The Describe and Select permissions are granted to the RAM user Allen to allow Allen to read the metadata and data of the table. Sample commands: 
    -- Use the Alibaba Cloud account Bob@aliyun.com to access the project test_project_a. 
use test_project_a; 
-- Create a partitioned table named sale_detail in the project. 
create table if not exists sale_detail
(
shop_name     string,
customer_id   string,
total_price   double
)
partitioned by (sale_date string, region string);
-- Add the RAM user Allen to the project as a member. 
add user RAM$Bob@aliyun.com:Allen;
-- Grant the permissions to the RAM user Allen. 
grant Describe, Select on table sale_detail to USER RAM$Bob@aliyun.com:Allen;
-- Query the authorization result. 
show grants for RAM$Bob@aliyun.com:Allen; 
-- The following authorization result is returned: 
Authorization Type: ACL
[user/RAM$Bob@aliyun.com:Allen]
A       projects/test_project_a/tables/sale_detail: Describe | Select
  • Example 2: Grant permissions to a user
    In this example, all permissions on the columns shop_name and customer_id in the table sale_detail created in Example 1 are granted to the RAM user Alice. Sample commands: 
    -- Use the Alibaba Cloud account Bob@aliyun.com to access the project test_project_a. 
use test_project_a; 
-- Add the RAM user Alice to the project as a member. 
add user RAM$Bob@aliyun.com:Alice;
-- Grant the permissions to the RAM user Alice. 
grant All on table sale_detail (shop_name, customer_id) to USER RAM$Bob@aliyun.com:Alice;
-- Query the authorization result. 
show grants for RAM$Bob@aliyun.com:Alice; 
-- The following authorization result is returned: 
Authorization Type: ACL
[user/RAM$Bob@aliyun.com:Alice]
A       projects/test_project_a/tables/sale_detail/customer_id: All
A       projects/test_project_a/tables/sale_detail/shop_name: All
  • Example 3: Revoke permissions from a user
    In this example, the permissions that are granted to the RAM users Allen and Alice in Example 1 and Example 2 are revoked. Sample commands: 
    -- Use the Alibaba Cloud account Bob@aliyun.com to access the project test_project_a. 
use test_project_a; 
-- Revoke the Describe and Select permissions that are granted to the RAM user Allen. 
revoke Describe, Select on table sale_detail (shop_name, customer_id) from USER RAM$Bob@aliyun.com:Allen;
-- Revoke the permissions on the table that are granted to the RAM user Alice. 
revoke All on table sale_detail (shop_name, customer_id) from USER RAM$Bob@aliyun.com:Alice;
-- Query the permissions of the RAM user Allen. The RAM user Allen does not have the Describe and Select permissions. 
show grants for RAM$Bob@aliyun.com:Allen; 
-- Query the permissions of the RAM user Alice. The RAM user Alice does not have the permissions on the table. 
show grants for RAM$Bob@aliyun.com:Alice;
  • Example 4: Use a role to grant the same permissions to multiple users
    In this example, the RAM users Alice and Tom and the Alibaba Cloud account Lily@aliyun.com are granted the CreateInstance, CreateResource, CreateFunction, CreateTable, and List permissions on the project test_project_a. Sample commands: 
    -- Use the Alibaba Cloud account Bob@aliyun.com to access the project test_project_a. 
use test_project_a; 
-- Add the RAM users Alice and Tom and the Alibaba Cloud account Lily@aliyun.com to the project as members. 
add user RAM$Bob@aliyun.com:Alice;
add user RAM$Bob@aliyun.com:Tom;
add user ALIYUN$Lily@aliyun.com;
-- Create a role named Worker. 
create role Worker; 
-- Assign the role Worker to the three members. 
grant Worker TO RAM$Bob@aliyun.com:Alice; 
grant Worker TO RAM$Bob@aliyun.com:Tom; 
grant Worker TO ALIYUN$Lily@aliyun.com; 
-- Grant the CreateInstance, CreateResource, CreateFunction, CreateTable, and List permissions on the project to the role Worker. 
grant CreateInstance, CreateResource, CreateFunction, CreateTable, List on project test_project_a TO ROLE Worker;
-- Query the permissions of the Alibaba Cloud account Lily@aliyun.com. 
show grants for ALIYUN$Lily@aliyun.com; 
-- The following authorization result is returned: The authorization result shows that the Alibaba Cloud account Lily@aliyun.com is granted the preceding permissions. 
[roles]
worker

Authorization Type: ACL
[role/worker]
A       projects/test_project_a: CreateTable | CreateResource | CreateInstance | CreateFunction | List
  • Example 5: Revoke the same permissions that are granted by using a role from multiple users
    In this example, the same permissions that are granted to the RAM users Alice and Tom and the Alibaba Cloud account Lily@aliyun.com in Example 3 are revoked. Sample commands: 
    -- Use the Alibaba Cloud account Bob@aliyun.com to access the project test_project_a. 
use test_project_a; 
-- Revoke the role Worker from the RAM users Alice and Tom and the Alibaba Cloud account Lily@aliyun.com. 
revoke Worker from RAM$Bob@aliyun.com:Alice;
revoke Worker from RAM$Bob@aliyun.com:Tom;
revoke Worker from ALIYUN$Lily@aliyun.com;
-- Query the permissions of the Alibaba Cloud account Lily@aliyun.com. The Alibaba Cloud account Lily@aliyun.com does not have the permissions of the role Worker. 
show grants for ALIYUN$Lily@aliyun.com;

What to do next

After you have a command of how the ACL-based access control method works, you can perform the following operations based on your business requirements: