MaxCompute provides the download control feature. This feature allows you to manage the permissions of users or roles to download tables, resources, functions, or instances by using Tunnel commands. This helps improve the security of project data and prevents data leaks. This topic describes the commands that are used for download control in MaxCompute. This topic also provides examples on how to use these commands to perform download control.

Background information

You can use Tunnel commands to download tables, resources, functions, or instances in your MaxCompute project. However, the download operations may cause data leaks. To prevent data leaks, you must manage download permissions.

After you create a MaxCompute project, the download control feature is disabled for the project by default. All users or roles in the project can download all the tables, resources, functions, and instances in the project. The project owner or a user with the Super_Administrator role can run the setproject odps.security.enabledownloadprivilege=true|false; command at the project level to enable or disable the download control feature.

The following table describes the scenarios for which the download control feature is suitable.

Scenario Description Authorized by Operation platform
Single-user authorization Grants a single user the permissions to download specified tables, resources, functions, or instances. See the Authorized by column in Permissions.
Role-based authorization Grants a single role the permissions to download specified tables, resources, functions, or instances and assigns the role to multiple users. This way, the users are granted the download permissions.

Prerequisites

Before you use the download control feature, make sure that the following information is obtained:
  • 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$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 types and names of the objects.

    You can run the show tables;, list resources;, list functions;, or show instances; command on the MaxCompute client to obtain the names of tables (views), resources, functions, or instances.

Limits

Before you use the download control feature, take note of the following limits:
  • Only existing subjects and objects support authorization for download control.
  • When you grant the download permissions to a user, you cannot use wildcards (*) to specify objects. If you need to use wildcards (*) to specify objects, you can perform role-based authorization.

Usage notes

Before you use the download control feature, take note of the following points:
  • If you delete an object, MaxCompute automatically revokes all the granted download permissions on the object.
  • 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.

Syntax

  • Syntax for the command that is used to grant download permissions
    grant Download on <object_type> <object_name> to <subject_type> <subject_name>;
  • Syntax for the command that is used to revoke download permissions
    revoke Download on <object_type> <object_name> from <subject_type> <subject_name>;

The following table describes the parameters that are used in the download control commands.

Parameter Required Description
object_type Yes The type of the object. You can specify only one object type for a single authorization operation.
Valid values:
  • Table
  • Resource
  • Function
  • Instance
object_name Yes The name of the object. You can obtain the name of an object by using one of the following methods:
  • Table or view name: You can run the show tables; command on the MaxCompute client to obtain the name of a table or view.
  • Resource name: You can run the list resources; command on the MaxCompute client to obtain the name of a resource.
  • Function name: You can run the list functions; command on the MaxCompute client to obtain the name of a function.
  • Instance name: You can run the show instances; command on the MaxCompute client to obtain the ID of an instance. Instance names are the same as instance IDs in MaxCompute.

If you grant download permissions to a role, you can use wildcards (*) to specify the objects. For example, table taobao* indicates all the tables whose name starts with taobao.

subject_type Yes The type of the subject. Valid values:
  • USER: an Alibaba Cloud account or a RAM user.
  • ROLE: a role.
subject_name Yes The name of the subject. You can specify only one user or role for a single authorization operation.

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

Examples

The Alibaba Cloud account Bob@aliyun.com is the owner of the test_project_a project. Allen, Tom, and Alice are the RAM users of Bob@aliyun.com. The download control feature is enabled for the test_project_a project. In the following examples, all the authorization operations are performed on the MaxCompute client.
  • Example 1: Grant download permissions to a RAM user.
    Add Allen to the test_project_a project and grant Allen the permissions to download data from the sale_detail table. Sample commands:
    -- Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
    use test_project_a; 
    -- Add Allen as a project member. 
    add user RAM$Bob@aliyun.com:Allen;
    -- Grant Allen the permissions to download data from the sale_detail table in the test_project_a project. 
    grant Download on table sale_detail to USER RAM$Bob@aliyun.com:Allen;
    -- Query the permissions of Allen. 
    show grants for RAM$Bob@aliyun.com:Allen; 
    -- The following result is returned. The result indicates that Allen has download permissions. 
    Authorization Type: ACL
    [user/RAM$Bob@aliyun.com:Allen]
    A       projects/test_project_a/tables/sale_detail: Download
  • Example 2: Revoke download permissions from a RAM user.
    Revoke the download permissions that are granted in Example 1 from Allen.
    -- Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
    use test_project_a; 
    -- Revoke the download permissions from Allen. 
    revoke Download on table sale_detail from USER RAM$Bob@aliyun.com:Allen;
    -- Query the permissions of Allen. The permissions of Allen do not include the download permissions. 
    show grants for RAM$Bob@aliyun.com:Allen;  
  • Example 3: Grant the download permissions to multiple RAM users based on a role.
    Grant Alice and Tom the permissions to download data from the tables whose name starts with tb_ in the test_project_a project. Sample commands:
    -- Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
    use test_project_a; 
    -- Add Alice and Tom as project members. 
    add user RAM$Bob@aliyun.com:Alice;
    add user RAM$Bob@aliyun.com:Tom;
    -- Create a role named Worker. 
    create role Worker; 
    -- Assign the Worker role to Alice and Tom. 
    grant Worker TO RAM$Bob@aliyun.com:Alice; 
    grant Worker TO RAM$Bob@aliyun.com:Tom; 
    -- Grant the Worker role the permissions to download the tables whose name starts with tb_ in the test_project_a project. 
    grant Download on table tb_* to ROLE Worker;
    -- Query the permissions of Alice. 
    describe role Worker;
    -- The following result is returned. A indicates that the download permissions are granted to Alice. 
    Authorization Type: Policy
    [role/worker]
    A       projects/test_project_a/tables/tb_*: Download
  • Example 4: Revoke the download permissions that are granted based on a role from multiple RAM users.
    Revoke the download permissions that are granted based on the Worker role in Example 3 from Alice and Tom.
    -- Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
    use test_project_a; 
    -- Revoke the Worker role from Alice and Tom. 
    revoke Worker from RAM$Bob@aliyun.com:Alice;
    revoke Worker from RAM$Bob@aliyun.com:Tom;
    -- Query the permissions of Alice. The permissions of Alice do not include the download permissions. 
    show grants for RAM$Bob@aliyun.com:Alice; 

What to do next

After you understand the download control feature, you can perform the following operations based on your business requirements: