Download control lets you manage who can export data from your MaxCompute project through Tunnel commands. Without it, every user and role in a project can download any table or instance freely, which creates a risk of data exfiltration. Once you enable the feature, only users or roles with explicit download permissions can export data.
How it works
By default, download control is disabled for a new project. After you enable it at the project level, all Tunnel-based download operations are gated on explicit permissions.
The following table shows which objects support download permissions and how they can be authorized:
| Object type | Valid values | Wildcard support |
|---|---|---|
Table | Table or view name | Role-based only (*) |
Instance | Instance name (same as instance ID) | Not supported for wildcards |
Two authorization models are available:
| Model | How it works | Best for |
|---|---|---|
| Single-user authorization | Grant download permissions directly to one user on specific tables or instances | Targeted access for individual users |
| Role-based authorization | Grant download permissions to a role, then assign the role to multiple users | Managing access for groups; supports wildcards (*) in object names |
Limits and usage notes
Limits:
Authorization only applies to subjects (users or roles) and objects that already exist. You cannot pre-authorize future subjects or objects.
When granting permissions directly to a user, wildcards (
*) are not supported in object names. This restriction exists to prevent unintended broad access grants—use role-based authorization when you need wildcard patterns.
Usage notes:
When an object is deleted, MaxCompute automatically revokes all download permissions on that object.
When a user is removed from a project, their permissions are retained. If the user is re-added, those permissions become active again. To clear residual permissions, see Completely clear the residual permission information of a removed user.
Enable download control
Permissions required: Project owner or Super_Administrator role.
Run the following command at the project level:
setproject odps.security.enabledownloadprivilege=true;To disable download control:
setproject odps.security.enabledownloadprivilege=false;Grant and revoke download permissions
Permissions required: To grant or revoke permissions on an object, see the Authorized by column in Permissions.
Run all commands on the MaxCompute client, MaxCompute Studio, or DataWorks console.
Workflow
For both single-user and role-based authorization, follow this sequence:
Confirm the user or role is a project member. Run
list users;orlist roles;on the MaxCompute client to look up names. To add users or roles, see User planning and management or Role planning.Confirm the names of the tables or instances to control. Run
show tables;orshow instances;to list available objects.Run the
grantorrevokecommand.Verify the result with
show grantsordescribe role.
Syntax
Grant download permissions:
grant Download on <object_type> <object_name> to <subject_type> <subject_name>;Revoke download permissions:
revoke Download on <object_type> <object_name> from <subject_type> <subject_name>;Parameters
| Parameter | Required | Description |
|---|---|---|
object_type | Yes | Type of the object. Valid values: Table, Instance. One object type per command. |
object_name | Yes | Name of the table, view, or instance. For role-based authorization, wildcards are supported—for example, table taobao* matches all tables whose names start with taobao. Run show tables; or show instances; to get names. |
subject_type | Yes | Type of the subject. Valid values: USER (an Alibaba Cloud account or RAM user), ROLE (a role). |
subject_name | Yes | Name of the user or role. One subject per command. Use ALIYUN$<account> for Alibaba Cloud accounts and RAM$<account>:<username> for RAM users. Run list users; or list roles; to get names. |
Examples
The following examples use this setup: username@example.com owns test_project_a. Allen, Tom, and Alice are RAM users under that account. Download control is enabled for the project.
Example 1: Grant download permissions to a RAM user
Add Allen to the project and grant download permissions on the sale_detail table:
-- Switch to the project.
use test_project_a;
-- Add Allen as a project member.
add user RAM$username@example.com:Allen;
-- Grant Allen download permissions on sale_detail.
grant Download on table sale_detail to USER RAM$username@example.com:Allen;
-- Verify Allen's permissions.
show grants for RAM$username@example.com:Allen;Expected output:
Authorization Type: ACL
[user/RAM$username@example.com:Allen]
A projects/test_project_a/tables/sale_detail: DownloadExample 2: Revoke download permissions from a RAM user
Revoke the permissions granted in Example 1:
-- Switch to the project.
use test_project_a;
-- Revoke Allen's download permissions.
revoke Download on table sale_detail from USER RAM$username@example.com:Allen;
-- Verify that permissions are removed.
show grants for RAM$username@example.com:Allen;Example 3: Grant download permissions to multiple users via a role
Grant Alice and Tom download permissions on all tables whose names start with tb_:
-- Switch to the project.
use test_project_a;
-- Add Alice and Tom as project members.
add user RAM$username@example.com:Alice;
add user RAM$username@example.com:Tom;
-- Create a role.
create role Worker;
-- Assign the role to Alice and Tom.
grant Worker TO RAM$username@example.com:Alice;
grant Worker TO RAM$username@example.com:Tom;
-- Grant the Worker role download permissions on all tb_* tables.
grant Download on table tb_* to ROLE Worker;
-- Verify the role's permissions.
describe role Worker;Expected output:
Authorization Type: Policy
[role/worker]
A projects/test_project_a/tables/tb_*: DownloadExample 4: Revoke role-based download permissions
Revoke the permissions granted in Example 3 from Alice and Tom:
-- Switch to the project.
use test_project_a;
-- Remove the Worker role from Alice and Tom.
revoke Worker from RAM$username@example.com:Alice;
revoke Worker from RAM$username@example.com:Tom;
-- Verify that Alice's permissions no longer include download access.
show grants for RAM$username@example.com:Alice;