Authorize permissions using policy-based access control - MaxCompute

MaxCompute provides policy-based access control for complex and flexible permission settings, ideal for large enterprises and scenarios that require fine-grained control. Unlike access control list (ACL) authorization, policy-based access control also supports a blacklist, allowing you to create policies that grant or deny a role permission to perform specific operations on specific objects. After you attach the role to a user, the permissions take effect.

Background

Policy-based access control supports whitelist and blacklist authorization. You can grant (whitelist) or deny (blacklist) a role permission to perform specific operations on specific objects.

This access control method resolves authorization issues that cannot be resolved using ACL-based access control. For example, a user is assigned the developer role and has the permissions to drop tables by default. If you want to deny the role from dropping tables, you can use this access control method.

After a MaxCompute project is created, policy-based access control is enabled by default. The project owner can run the set CheckPermissionUsingPolicy=true|false; command in the MaxCompute project to enable or disable this feature.

Policy-based access control applies to the following scenarios.

Scenario	Description	Authorizer	Authorization endpoint
Grant permissions to users based on roles	Grant a role the permission to allow or deny one or more operations on a specific object. Then, attach the role to multiple users. The users inherit the permissions of the role.	See the Authorizer column in MaxCompute permissions.	MaxCompute client MaxCompute Studio Connect using DataWorks
Use a custom role for fine-grained authorization for a user with a built-in role	If a user is already assigned a built-in role and you need more fine-grained control over their permissions, ACL authorization is not sufficient. In this case, use policy-based access control to create a new role. You can then grant or deny the role permission to perform operations on project objects and attach the role to the user for fine-grained permission management.	See the Authorizer column in MaxCompute permissions.	MaxCompute client MaxCompute Studio Connect using DataWorks

Usage notes

Before you use policy-based access control, note the following prerequisites and precautions.

Prerequisites:
- Policy-based access control supports authorization only for existing roles. Confirm the name of the role to be authorized and ensure that the role has been added to the MaxCompute project. You can run the list roles; command on the MaxCompute client to retrieve role information. To create a new role, see Role planning.
- The object type, object name, and the actions to grant.
  
  For more information about object types and actions, see MaxCompute permissions.
Precautions:
- If both whitelist and blacklist authorizations are configured, the blacklist takes precedence.
- Policy-based access control lets you grant permissions on objects that do not exist. When you delete an object, the associated policy authorization information is not deleted. The authorizer must be aware of the security risks that can arise from deleting and then recreating an object with the same name.
- When a user is removed, their permissions are retained. If the user is added back to the project later, their previous permissions are automatically restored. To permanently clear a user's permissions, see Clear residual permissions of a removed user.

Syntax

The policy-based access control commands are formatted as follows:

Policy authorization

GRANT <actions> ON <object_type> <object_name> 
TO ROLE <role_name> 
PRIVILEGEPROPERTIES("policy" = "true", "allow"="{true|false}"[, "conditions"= "<conditions>"]);

Revoke policy authorization

REVOKE <actions> ON <object_type> <object_name> 
FROM ROLE <role_name> 
PRIVILEGEPROPERTIES("policy" = "true", "allow"="{true|false}");

The following table describes the parameters.

Parameter		Required	Description
actions		Yes	The action to grant. You can specify multiple actions in a single command. If you specify multiple actions, separate them with commas (,). For more information about the valid values, see MaxCompute permissions.
object_type		Yes	The type of the object to grant permissions on. You can specify only one object type in a single command. For more information about the valid values, see MaxCompute permissions.
object_name		Yes	The name of the object to grant permissions on. You can obtain the name in one of the following ways: Project name: You can log on to the MaxCompute console, switch the region in the upper-left corner, and then obtain the MaxCompute project name from the Projects tab. Table or view: To obtain the name of a table or view, run the `show tables;` command on the MaxCompute client. Model name: You can use the MaxCompute client to execute the `show models;` command to obtain the model name. Resource name: You can obtain the resource name by executing the `list resources;` command on the MaxCompute client. Function name: You can run the `list functions;` command on the MaxCompute client to obtain the function name. Instance Name: You can obtain the instance ID by executing the `show instances;` command on the MaxCompute client. You can use an asterisk () as a wildcard in an object name. For example, `table taobao` indicates all tables whose names start with `taobao`. Note You can use a wildcard (*) only when you grant permissions to a ROLE. Wildcards are not supported when you grant permissions to a USER.
role_name		Yes	The name of the role to authorize. You can specify only one role in a single command. You can run the `list roles;` command on the MaxCompute client to obtain the role name.
privilegeproperties	policy	Yes	Set the value to true. This indicates that the policy-based access control method is used.
	allow	Required for whitelist authorization	The authorization mechanism. Valid values: true: Allows the specified operation on the specified object. false: Denies the specified operation on the specified object. This is the blacklist mechanism.
	conditions	No	Controls permissions based on dimensions such as the source of the request message and the access method. For more information about the valid values, see Conditions.

Policy-based access control examples

In the following examples, Bob@aliyun.com is the owner of the test_project_a project, and Allen and Tom are Resource Access Management (RAM) users under the account Bob@aliyun.com. Allen has the Admin role for test_project_a. The examples show how to perform authorization operations on the MaxCompute client:

Example 1: Grant permissions to a user based on a role (blacklist)

Deny Tom from deleting tables that start with tb_.

The following example shows how to implement policy authorization using commands:

-- Bob enters the test_project_a project.
USE test_project_a;
-- Create the Worker role.
CREATE ROLE Worker;
-- Add the user Tom as a project member.
ADD USER RAM$Bob@aliyun.com:Tom;
-- Attach the Worker role to the user Tom.
GRANT Worker TO RAM$Bob@aliyun.com:Tom;
-- Deny the Worker role from deleting tables that start with tb_ in the test_project_a project.
GRANT Drop ON TABLE tb_* TO ROLE Worker PRIVILEGEPROPERTIES("policy" = "true", "allow"="false");
-- View the authorization result for the user Tom.
SHOW GRANTS FOR RAM$Bob@aliyun.com:Tom;
-- The following authorization result is returned. D indicates Deny. Deleting tables that start with tb_ is denied.
Authorization Type: Policy
[role/worker]
D      projects/test_project_a/tables/tb_*: Drop

The following example shows how to implement policy authorization in the console:
1. Log on to the MaxCompute console and select a region in the upper-left corner.
2. In the left-side navigation pane, choose Manage Configurations > Projects.
3. On the Projects page, locate the target project and click Manage in the Actions column.
4. On the Role Permissions tab, click Create Project-level Role.
5. In the Create Role dialog box, create a Resource role, enter a Role Name, and define the authorization policy.
  The following is a sample policy:
```
{
    "Statement":[
        {
            "Action":[
                "odps:Drop"
            ],
            "Effect":"Deny",
            "Resource":[
                "acs:odps:*:projects/test_project_a/tables/tb_*"
            ]
        }
    ],
    "Version":"1"
}
```
6. On the Role Permissions tab, find the new role, click Manage Members in the Actions column, and add RAM$Bob@aliyun.com:Tom to the role.

Example 2: Revoke policy authorization (blacklist)

Based on Example 1, revoke the authorization from the user Tom.

-- Bob enters the test_project_a project.
USE test_project_a; 
-- Revoke the Worker role from the user Tom.
REVOKE Worker FROM RAM$Bob@aliyun.com:Tom;
-- View the authorization result for the user Tom. The permission list does not contain the Drop permission information.
SHOW GRANTS FOR RAM$Bob@aliyun.com:Tom;

Example 3: Grant permissions to a user based on a role (whitelist)

Allow Tom to update data in tables that start with tb_.

The following example shows how to implement policy authorization using commands:

-- Bob enters the test_project_a project.
USE test_project_a; 
-- Create the Worker role.
CREATE ROLE Worker; 
-- Add the user Tom as a project member.
ADD USER RAM$Bob@aliyun.com:Tom;
-- Attach the Worker role to the user Tom.
GRANT Worker TO RAM$Bob@aliyun.com:Tom; 
-- Allow the Worker role to update data in tables that start with tb_ in the test_project_a project.
GRANT Update ON TABLE tb_* TO ROLE Worker PRIVILEGEPROPERTIES("policy" = "true", "allow"="true");
-- View the authorization result for the user Tom.
SHOW GRANTS FOR RAM$Bob@aliyun.com:Tom; 
-- The following authorization result is returned. A indicates Allow. You can update data in tables that start with tb_.
Authorization Type: Policy
[role/worker]
A       projects/test_project_a/tables/tb_*: Update

The following example shows how to implement policy authorization in the console:
1. Log on to the MaxCompute console and select a region in the upper-left corner.
2. In the left-side navigation pane, choose Manage Configurations > Projects.
3. On the Projects page, locate the target project and click Manage in the Actions column.
4. On the Role Permissions tab, click Create Project-level Role.
5. In the Create Role dialog box, create a Resource role, enter a Role Name, and define the authorization policy.
  The following is a sample policy:
```
{
    "Statement":[
        {
            "Action":[
                "odps:Update"
            ],
            "Effect":"Allow",
            "Resource":[
                "acs:odps:*:projects/test_project_a/tables/tb_*"
            ]
        }
    ],
    "Version":"1"
}
```
6. On the Role Permissions tab, find the new role, click Manage Members in the Actions column, and add RAM$Bob@aliyun.com:Tom to the role.

Example 4: Revoke policy authorization (whitelist)

Based on Example 3, revoke the authorization from the user Tom.

-- Bob enters the test_project_a project.
USE test_project_a; 
-- Revoke the Worker role from the user Tom.
REVOKE Worker FROM RAM$Bob@aliyun.com:Tom;
-- View the authorization result for the user Tom. The permission list does not contain the Update permission information.
SHOW GRANTS FOR RAM$Bob@aliyun.com:Tom;

Example 5: Perform fine-grained authorization for a user with a built-in role

Deny Allen from deleting all tables in the test_project_a project.

The following example shows how to implement policy authorization using commands:

-- Bob enters the test_project_a project.
USE test_project_a;
-- Create the Worker role.
CREATE ROLE Worker;
-- Attach the Worker role to the user Allen.
GRANT Worker TO RAM$Bob@aliyun.com:Allen;
-- Deny the Worker role from deleting all tables in the test_project_a project.
GRANT Drop ON TABLE * TO ROLE Worker PRIVILEGEPROPERTIES("policy" = "true", "allow"="false");
-- View the authorization result for the user Allen.
SHOW GRANTS FOR RAM$Bob@aliyun.com:Allen;
-- The following authorization result is returned. Deleting all tables is denied.
[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
-- A in AG indicates Allow. G in AG indicates With Grant Option, which lets you grant permissions on the object.
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

The following example shows how to implement policy authorization in the console:
1. Log on to the MaxCompute console and select a region in the upper-left corner.
2. In the left-side navigation pane, choose Manage Configurations > Projects.
3. On the Projects page, locate the target project and click Manage in the Actions column.
4. On the Role Permissions tab, click Create Project-level Role.
5. In the Create Role dialog box, create a Resource role, enter a Role Name, and define the authorization policy.
  The following is a sample policy:
```
{
    "Statement":[
        {
            "Action":[
                "odps:Drop"
            ],
            "Effect":"Deny",
            "Resource":[
                "acs:odps:*:projects/test_project_a/tables/*"
            ]
        }
    ],
    "Version":"1"
}
```
6. On the Role Permissions tab, find the new role, click Manage Members in the Actions column, and add RAM$Bob@aliyun.com:Allen to the role.

Example 6: Revoke authorization for a user with a built-in role

Based on Example 5, revoke the authorization from the user Allen. The following is a sample command.

-- Bob enters the test_project_a project.
USE test_project_a;
-- Revoke the Worker role from the user Allen.
REVOKE Worker FROM RAM$Bob@aliyun.com:Allen;
-- View the authorization result for the user Allen. The permission list does not contain the Drop permission information.
SHOW GRANTS FOR RAM$Bob@aliyun.com:Allen;

Example 7: Grant a user (Tom) the permission to query all tables based on a role (whitelist)

The following example shows how to implement policy authorization using commands:

-- Bob enters the test_project_a project.
USE test_project_a;
-- Create the Worker role.
CREATE ROLE Worker;
-- Add the user Tom as a project member.
ADD USER RAM$Bob@aliyun.com:Tom;
-- Attach the Worker role to the user Tom.
GRANT Worker TO RAM$Bob@aliyun.com:Tom;
-- Allow the Worker role to query all tables in the test_project_a project.
GRANT Describe,Select ON TABLE * TO ROLE Worker PRIVILEGEPROPERTIES("policy" = "true", "allow"="true");
-- View the authorization result for the user Tom.
SHOW GRANTS FOR RAM$Bob@aliyun.com:Tom;
-- The following authorization result is returned. A indicates Allow. You can query all tables in the test_project_a project.
Authorization Type: Policy
[role/worker]
A      projects/test_project_a/tables/*: Describe | Select

The following example shows how to implement policy authorization in the console:
1. Log on to the MaxCompute console and select a region in the upper-left corner.
2. In the left-side navigation pane, choose Manage Configurations > Projects.
3. On the Projects page, locate the target project and click Manage in the Actions column.
4. On the Role Permissions tab, click Create Project-level Role.
5. In the Create Role dialog box, create a Resource role, enter a Role Name, and define the authorization policy.
  The following is a sample policy:
```
{
    "Statement":[
        {
            "Action":[
                "odps:Describe",
                "odps:Select"
            ],
            "Effect":"Allow",
            "Resource":[
                "acs:odps:*:projects/test_project_a/tables/*"
            ]
        }
    ],
    "Version":"1"
}
```
6. On the Role Permissions tab, find the new role, click Manage Members in the Actions column, and add RAM$Bob@aliyun.com:Tom to the role.

What to do next

After you configure policy-based access control, you can perform the following operations as needed:

For more information about policy-based access control, see the following topics:

For authorization practices of policy-based access control, see Policy-based access control practices.
To manage operation permissions more granularly for users with built-in roles, see Manage permissions for users with built-in roles based on policies.
For frequently asked questions about permission management in MaxCompute, see 权限管理常见问题.