All Products
Search
Document Center

MaxCompute:ACL-based access control

Last Updated:Jul 19, 2024

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 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 whom 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$<account_id>. If the account of the user is a RAM user, record the RAM user in the format of RAM$<account_id>:<RAM user ID>. If the account of the user is a RAM role, record the RAM role in the format of `RAM$<account_id>:role/<Name of the RAM role>`.

    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.

  • 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 MaxCompute 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 MaxCompute 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 MaxCompute permissions.

object_name

Yes

The name of the object whose permissions are granted. You can obtain the name of an object by using one of the following methods:

  • Project: To view the name of a MaxCompute project, log on to the MaxCompute console. In the top navigation bar, select a region. Then, view the name of the MaxCompute project on the Project management tab. When you query information about a project, you can only obtain information about the current 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 access control on specific columns 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 permissions are granted or the name of the role to which permissions are granted. You can specify only an account or a role in a single statement. The name must meet the following format requirements:

  • Alibaba Cloud account: ALIYUN$<account_id>.

  • RAM user: RAM$<account_id>:<RAM user ID>.

  • RAM role: `RAM$<account_id>:role/<Name of the RAM role>`.

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

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 (user ID: 5527xxxxxxxx5788) is the owner of the project test_project_a. Allen (user ID: 1652xxxxxxxxxx1538), Alice (user ID: 2763xxxxxxxxxx1649), and Tom (user ID: 3874xxxxxxxxxx1850) 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:

    -- Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
    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$5527xxxxxxxx5788:1652xxxxxxxxxx1538;
    -- Grant the permissions to the RAM user Allen. 
    grant Describe, Select on table sale_detail to USER RAM$5527xxxxxxxx5788:1652xxxxxxxxxx1538;
    -- Query the authorization result. 
    show grants for RAM$5527xxxxxxxx5788:1652xxxxxxxxxx1538; 
    -- The following authorization result is returned: 
    Authorization Type: ACL
    [user/RAM$5527xxxxxxxx5788:1652xxxxxxxxxx1538]
    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:

    -- Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
    use test_project_a; 
    -- Add the RAM user Alice to the project as a member. 
    add user RAM$5527xxxxxxxx5788:2763xxxxxxxxxx1649;
    -- Grant the permissions to the RAM user Alice. 
    grant All on table sale_detail (shop_name, customer_id) to USER RAM$5527xxxxxxxx5788:2763xxxxxxxxxx1649;
    -- Query the authorization result. 
    show grants for RAM$5527xxxxxxxx5788:2763xxxxxxxxxx1649; 
    -- The following authorization result is returned: 
    Authorization Type: ACL
    [user/RAM$5527xxxxxxxx5788:2763xxxxxxxxxx1649]
    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:

    -- Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
    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$5527xxxxxxxx5788:1652xxxxxxxxxx1538;
    -- 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$5527xxxxxxxx5788:2763xxxxxxxxxx1649;
    -- Query the permissions of the RAM user Allen. The RAM user Allen does not have the Describe and Select permissions. 
    show grants for RAM$5527xxxxxxxx5788:1652xxxxxxxxxx1538; 
    -- Query the permissions of the RAM user Alice. The RAM user Alice does not have the permissions on the table. 
    show grants for RAM$5527xxxxxxxx5788:2763xxxxxxxxxx1649; 

  • 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 (user ID: 5638xxxxxxxx6899) are granted the CreateInstance, CreateResource, CreateFunction, CreateTable, and List permissions on the project test_project_a. Sample commands:

    -- Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
    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$5527xxxxxxxx5788:2763xxxxxxxxxx1649;
    add user RAM$5527xxxxxxxx5788:3874xxxxxxxxxx1850;
    add user ALIYUN$5638xxxxxxxx6899;
    -- Create a role named Worker. 
    create role Worker; 
    -- Assign the role Worker to the three members. 
    grant Worker TO RAM$5527xxxxxxxx5788:2763xxxxxxxxxx1649; 
    grant Worker TO RAM$5527xxxxxxxx5788:3874xxxxxxxxxx1850; 
    grant Worker TO ALIYUN$5638xxxxxxxx6899; 
    -- 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$5638xxxxxxxx6899; 
    -- 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:

    -- Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
    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$5527xxxxxxxx5788:2763xxxxxxxxxx1649;
    revoke Worker from RAM$5527xxxxxxxx5788:3874xxxxxxxxxx1850;
    revoke Worker from ALIYUN$5638xxxxxxxx6899;
    -- 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$5638xxxxxxxx6899; 

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: