All Products
Search

This Product

    MaxCompute:GRANT

    Document Center

    MaxCompute:GRANT

    Last Updated:Apr 10, 2024

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

    ACL-based access control

    • 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$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 execute the list users; or list roles; statement on the MaxCompute client to query the name of the user account or role.

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

      • The type of 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.

    • Syntax

      The following code provides the syntax of the GRANT statement that you can use to perform ACL-based access control:

      • ACL-based access control 

        grant <actions> on <object_type> <object_name> 
[(<column_list>)] to <subject_type> <subject_name> 
[privilegeproperties("conditions" = "<conditions>", "expires"="<days>")];

      • 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 syntax.

        Parameter

        Required

        Description

        actions

        Yes

        The action that is allowed. You can specify one or more actions in a single statement.

        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 object on which permissions are granted. You can specify only one type of object in a single statement.

        For more information about the supported object types, see MaxCompute permissions.

        object_name

        Yes

        The name of the object whose permissions are granted. The following types of objects are supported:

        • Project: To obtain the name of a MaxCompute project, log on to the MaxCompute console. In the top navigation bar, select the region in which 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, execute the show tables; statement on the MaxCompute client.

        • Resource: To obtain the name of a resource, execute the list resources; statement on the MaxCompute client.

        • Function: To obtain the name of a function, execute the list functions; statement on the MaxCompute client.

        • Instance: To obtain the name of an instance, execute the show instances; statement 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 (*) to configure this parameter 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 statement. 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: an Alibaba Cloud account or a RAM user.

        • ROLE: a role.

        subject_name

        Yes

        The name of the user account or role to which you want to grant access permissions. You can specify only one user account or role for a single authorization operation.

        You can execute the list users; or list roles; statement 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 that are supported in conditions.

      var_name

      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

      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, statements are executed on the MaxCompute client.

      • Example 1: Grant permissions to a user

        Create a table named sale_detail in the project test_project_a, and grant the Describe and Select permissions on the sale_detail table to the RAM user Allen. Sample statements: 

        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$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 permissions of the RAM user Allen. 
show grants for RAM$Bob@aliyun.com:Allen; 
-- The following 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

        Grant all permissions on the columns shop_name and customer_id in the table sale_detail created in Example 1 to the RAM user Alice. Sample statements: 

        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$Bob@aliyun.com:Alice;
-- Grant the permissions on columns to the RAM user Alice. 
grant All on table sale_detail (shop_name, customer_id) to USER RAM$Bob@aliyun.com:Alice;
-- Query the permissions of Alice. 
show grants for RAM$Bob@aliyun.com:Alice; 
-- The following 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: Use a role to grant the same permissions to multiple users

        Grant the following permissions to the RAM users Alice and Tom and the Alibaba Cloud account Lily@aliyun.com: CreateInstance, CreateResource, CreateFunction, CreateTable, and List permissions on the project test_project_a. Sample statements: 

        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$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 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 test_project_a 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 result is returned. The 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

    Policy-based access control

    • Prerequisites

      Before you use the policy-based access control method, make sure that the following conditions are met:

      • The name of the role to which you want to grant permissions is obtained, and the role is added to your MaxCompute project.

        You can execute the list roles; statement on the MaxCompute client to query the name of the role.

        For more information about how to create a role, see 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

      You can use the policy-based access control method to grant permissions only to existing roles.

    • Precautions

      Before you use the policy-based access control method, take note of the following items:

      • If both the whitelist and blacklist mechanisms are used, the blacklist mechanism takes precedence.

      • You can use the policy-based access control method to grant a role the permissions on an object that does not exist. If you delete an existing object whose permissions are granted to a role, the permission information related to the object is retained. As a result, if you create an object that has the same name as the deleted object, security risks may exist.

      • 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

      The following code provides the syntax of the GRANT statement that you can use to perform policy-based access control:

      grant <actions> on <object_type> <object_name> 
to ROLE <role_name> 
privilegeproperties("policy" = "true", "allow"="{true|false}"[, "conditions"= "<conditions>" ,"expires"="<days>"]);

    • Parameters

      Parameter

      Required

      Description

      actions

      Yes

      The action that is allowed. You can specify multiple actions in a single statement.

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

      object_type

      Yes

      The type of object on which permissions are granted. You can specify only one type of object in a single statement.

      For more information about the supported object types, see MaxCompute permissions.

      object_name

      Yes

      The name of the object on which permissions are granted. The following types of objects are supported:

      • Project: To obtain the name of a MaxCompute project, log on to the MaxCompute console. In the top navigation bar, select the region in which 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, execute the show tables; statement on the MaxCompute client.

      • Resource: To obtain the name of a resource, execute the list resources; statement on the MaxCompute client.

      • Function: To obtain the name of a function, execute the list functions; statement on the MaxCompute client.

      • Instance: To obtain the name of an instance, execute the show instances; statement 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.

      role_name

      Yes

      The name of the role to which permissions are granted. You can specify only one role in a single statement.

      You can execute the list roles; statement on the MaxCompute client to query the name of the role.

      privilegeproperties

      policy

      Yes

      Set the value to true. The value true indicates that policy-based access control is used.

      allow

      Required if you want to use the whitelist mechanism

      Specifies whether to allow the specified action on the specified object. Valid values:

      • true: The specified action on the specified object is allowed.

      • false: The specified action on the specified object is not allowed. This value indicates the blacklist mechanism.

      conditions

      No

      The conditions used for policy-based access control, such as the source of a request message and the access method. For more information about the configurations of this parameter, see Conditions.

      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.

    • Examples

      The Alibaba Cloud account Bob@aliyun.com is the owner of the project test_project_a. Allen and Tom are the RAM users of Bob@aliyun.com. The RAM user Allen is assigned the Admin role of the project test_project_a. In the following examples, statements are executed on the MaxCompute client.

      • Example 1: Use a role to grant permissions to a user based on the blacklist mechanism

        Deny the RAM user Tom from dropping tables whose names start with tb_ from the project test_project_a. Sample statements: 

        Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
use test_project_a; 
-- Create a role named Worker. 
create role Worker; 
-- Add the RAM user Tom to the project as a member. 
add user RAM$Bob@aliyun.com:Tom;
-- Assign the role Worker to the RAM user Tom. 
grant Worker TO RAM$Bob@aliyun.com:Tom; 
-- Deny the role Worker from dropping tables whose names start with tb_ from the project. 
grant Drop on table tb_* to ROLE Worker privilegeproperties("policy" = "true", "allow"="false");
-- View the permissions of the RAM user Tom. 
show grants for RAM$Bob@aliyun.com:Tom; 
-- The following result is returned. The result D indicates Deny. The RAM user Tom is denied from dropping tables whose names start with tb_ from the project. 
Authorization Type: Policy
[role/worker]
D      projects/test_project_a/tables/tb_*: Drop

      • Example 2: Revoke the permissions that are granted by using the policy-based access control method based on the blacklist mechanism from a user

        Revoke the Drop permission that is granted to the RAM user Tom in Example 1. Sample statements: 

        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 user Tom. 
revoke Worker from RAM$Bob@aliyun.com:Tom;
-- View the permissions of the RAM user Tom. The RAM user Tom does not have the Drop permission. 
show grants for RAM$Bob@aliyun.com:Tom;

      • Example 3: Use a role to grant permissions to a user based on the whitelist mechanism

        Grant the Update permission to the RAM user Tom to allow Tom to update tables whose names start with tb_ in the project test_project_a. Sample statements: 

        Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
use test_project_a; 
-- Create a role named Worker. 
create role Worker; 
-- Add the RAM user Tom to the project as a member. 
add user RAM$Bob@aliyun.com:Tom;
-- Assign the role Worker to the RAM user Tom. 
grant Worker TO RAM$Bob@aliyun.com:Tom; 
-- Allow the role Worker to update tables whose names start with tb_ in the project test_project_a. 
grant Update on table tb_* to ROLE Worker privilegeproperties("policy" = "true", "allow"="true");
-- Query the permissions of the RAM user Tom. 
show grants for RAM$Bob@aliyun.com:Tom; 
-- The following result is returned. The result A indicates Allow. The RAM user Tom is allowed to update the tables whose names start with tb_ in the project. 
Authorization Type: Policy
[role/worker]
A       projects/test_project_a/tables/tb_*: Update

      • Example 4: Revoke the permissions that are granted by using the policy-based access control method based on the whitelist mechanism from a user

        Revoke the Update permission that is granted to the RAM user Tom in Example 3. Sample statements: 

        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 user Tom. 
revoke Worker from RAM$Bob@aliyun.com:Tom;
-- Query the permissions of the RAM user Tom. The RAM user Tom does not have the Update permission. 
show grants for RAM$Bob@aliyun.com:Tom;

      • Example 5: Grant finer-grained permissions to a user that is assigned a built-in role

        Deny the RAM user Allen from dropping any table from the project test_project_a. Sample statements: 

        Go to the test_project_a project by using the Alibaba Cloud account Bob@aliyun.com. 
use test_project_a; 
-- Create a role named Worker. 
create role Worker; 
-- Assign the role Worker to the RAM user Allen. 
grant Worker TO RAM$Bob@aliyun.com:Allen; 
-- Deny the role Worker from dropping any table from the project test_project_a. 
grant Drop on table * to ROLE Worker privilegeproperties("policy" = "true", "allow"="false");
-- Query the permissions of the RAM user Allen. 
show grants for RAM$Bob@aliyun.com:Allen; 
-- The following result is returned. The RAM user Allen is denied from dropping any table from the project. 
[roles]
role_project_admin, worker

Authorization Type: Policy
[role/role_project_admin]
A       projects/test_project_a: *
A       projects/test_project_a/instances/*: *
A       projects/test_project_a/jobs/*: *
A       projects/test_project_a/offlinemodels/*: *
A       projects/test_project_a/packages/*: *
A       projects/test_project_a/registration/functions/*: *
A       projects/test_project_a/resources/*: *
A       projects/test_project_a/tables/*: *
A       projects/test_project_a/volumes/*: *

[role/worker]
A       projects/test_project_a/tables/tb_*: Update
D       projects/test_project_a/tables/*: Drop

Authorization Type: ObjectCreator
AG      projects/test_project_a/tables/local_test: All
AG      projects/test_project_a/tables/mr_multiinout_out1: All
AG      projects/test_project_a/tables/mr_multiinout_out2: All
AG      projects/test_project_a/tables/ramtest: All
AG      projects/test_project_a/tables/wc_in: All
AG      projects/test_project_a/tables/wc_in1: All
AG      projects/test_project_a/tables/wc_in2: All
AG      projects/test_project_a/tables/wc_out: All

      • Example 6: Revoke permissions from a user that is assigned a built-in role

        Revoke the Drop permission that is granted to the RAM user Allen in Example 5. Sample statements: 

        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 user Allen. 
revoke Worker from RAM$Bob@aliyun.com:Allen;
-- Query the permissions of the RAM user Allen. The RAM user Allen does not have the Drop permission. 
show grants for RAM$Bob@aliyun.com:Allen;

    Grant a role to a user

    After you assign a role to a user, the user has all the permissions of the role.

    • Limits

      Before you assign a role to a user, you must grant the role the permissions on project objects. For more information, see Grant a role or user.

    • Syntax 

      grant <role_name> to <user_name>;

    • Parameters

      • role_name: required. The name of the role that you want to grant to a user.

      • user_name: required. The name of the Alibaba Cloud account or RAM user to which you want to grant the role. The format of an Alibaba Cloud account is ALIYUN$****@aliyun.com;. The format of a RAM user is RAM$****.

    • Examples 

      -- Grant the player role to the Alibaba Cloud account test_user@aliyun.com. 
grant player to ALIYUN$test_user@aliyun.com;

    Authorize a user or role to access a package

    This section describes how to grant a user or role the permission to access a package in a MaxCompute project where the package is installed.

    The installed package is a type of independent object in MaxCompute. If you want to access resources in a package, you must have the Read permission on the package. If you do not have the Read permission, the project owner and users that are assigned the Super_Administrator or Admin role can grant you the Read permission by using access control lists (ACLs). For more information about ACL-based access control, see ACL-based access control.

    • Syntax

      grant <actions> on package <project_name>.<package_name> to {USER|ROLE} <name>;

    • Precautions

      After the Read permission is granted to a user or role, the user or role can access the resources in the package only in the project where the package is installed. For more information about how to manage the permissions on packages in a fine-grained manner, see Access control for packages.

    • Parameters

      Parameter

      Required

      Description

      actions

      Yes

      The operation that is allowed to be performed on resources in the package. Set the value to Read.

      project_name

      Yes

      The name of the MaxCompute project to which the package belongs.

      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.

      package_name

      Yes

      The name of the package.

      You can run the show packages; command on the MaxCompute client to obtain the information about the package that you created.

      name

      Yes

      The name of the user account or role to which you want to grant access permissions. You can specify only one user account or role for a single authorization operation.

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

    • Examples

      Bella is a RAM user of the Alibaba Cloud account Amy@aliyun.com. Authorize Bella to access the datashare package. Sample statement: 

      -- Authorize Bella to access the datashare package. 
grant Read on package test_project_a.datashare to user RAM$Amy@aliyun.com:Bella;

    Related statements

    • CREATE PACKAGE: creates a package.

    • CREATE ROLE: creates a role in a MaxCompute project.

    • REVOKE: revokes access permissions on a package from a user or role.