All Products
Search
Document Center

Use tags to manage resources

Last Updated: Sep 28, 2020

This topic describes how to use tags to manage resources in API Gateway. Each tag is used to identify a group of resources that have common characteristics. This allows you to query and manage resources by group.

Each tag consists of two parts: a key and a value. When you tag a resource, you must specify the type of the resource. Tags for different types of resources are independent of each other, so are the tags in different regions. In API Gateway, the following types of resources can be tagged: API groups, API operations, plug-ins, and applications. The values of the ResourceType parameter are apiGroup, api, plugin, and app, respectively.

1. Scenarios

  1. Tags can be used to manage a large amount of resources by group. This makes it convenient to query and manage resources.

  2. Tags, combined with the permission management capability of Alibaba Cloud Resource Access Management (RAM), can be used to isolate resources for an Alibaba Cloud account and its RAM users. For more information, see section 3.1.

2. Limits

  • A resource can have a maximum of 20 tags.

  • For the same resource, the key of each tag must be unique. If you add a tag on a resource that already has a tag with the same key, the value of the new tag will override the value of the existing tag.

  • A key can be up to 64 Unicode characters in length. A value can be up to 128 Unicode characters in length.

  • Both keys and values are case-sensitive.

  • A key cannot start with aliyun or acs:, contain http:// or https://, or be left unspecified.

  • A value cannot contain http:// or https://. It can be a null string.

3. Permission control

3.1 Resource isolation for an Alibaba Cloud account and its RAM users

An Alibaba Cloud account is a primary account and can have many RAM users under it. These RAM users can be authorized to manage resources that are owned by the Alibaba Cloud account. For information about how to authorize RAM users to manage resources in API Gateway, see Use RAM to manage user permissions for API Gateway.

As the owner of an Alibaba Cloud account, you can use tags to classify resources. When you create an authorization policy, you can use these tags to specify the authorization condition. In this way, the authorized RAM user can only manage resources with the specified tags. For more information about how to create an authorization policy, see Policy elements. For example, your company has multiple departments. You can appoint an administrator, namely, create a RAM user, for each department. Then, you can authorize each RAM user to manage only resources with tags that are specific to their own department. The following examples show several scenarios in which permissions are granted based on tags.

Example 1:

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "apigateway:*",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "apigateway:tag/depart": "dep1"
        }
      }
    }
  ]
}

In this example, the authorized RAM user can manage only resources with the depart:dep1 tag, namely, all the resources that belong to Department 1. When this RAM user queries resources, the RAM user must include the Tag.1.Key=depart and Tag.1.Value=dep1 statements in the query condition.

Example 2:

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "apigateway:*",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "apigateway:tag/depart": ["dep2", "dep3"]
        }
      }
    }
  ]
}

In this example, the authorized RAM user can manage resources with the depart:dep2 tag or the depart:dep3 tag, namely, all the resources that belong to Department 2 or 3.

Example 3:

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "apigateway:*",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "apigateway:tag/depart": "dep2", 
         "apigateway:tag/Enviroment": "test"
        }
      }
    }
  ]
}

In this example, the authorized RAM user can manage only resources with both the depart:dep2 tag and the Enviroment:test tag. Namely, the RAM user can manage only resources that belong to Department 2 in the test environment.

API Gateway supports tag-based authorization for API groups, plug-ins, and applications. A RAM user who has permissions on an API group automatically has corresponding permissions on the API operations in the API group. You cannot use tags to authorize a RAM user to access specific API operations.

3.2 Limits of tag-based authorization

This section describes the limits of tag-based authorization on different types of API operations.

Limit on resource creation

When a RAM user creates a resource by calling an API operation in API Gateway, API Gateway checks whether the RAM user has permissions on all the resources to be used by the API operation. API Gateway also checks, based on the specified tag in the authorization policy that is attached to the RAM user, whether the RAM user has the permission to create the resource. Assume that a RAM user, who is authorized based on a tag, calls an API operation to create a resource, such as an API group, an application, or a plug-in. In this case, the RAM user must add the tag on the resource to be created in the API request.

For example, if the following authorization policy is attached to a RAM user, the RAM user must add the `depart:dept1` tag on each resource to be created.

{
    "Effect": "Allow",
    "Action": "apigateway:*",
     "Resource": "acs:apigateway:*:*:apigroup/*",
     "Condition": {
           "StringEquals": {
                "apigateway:tag/depart": "dep1"
            }
      }
}

Limit on resource management

When a RAM user calls an API operation to manage a resource in API Gateway, API Gateway checks whether the resource has the same tag that was used to authorize the RAM user. For example, if a RAM user calls the DeleteApp operation to delete an application, API Gateway allows the RAM user to delete the application only if the application has the same tag that was used to authorize the RAM user.

Limit on resource query

When a RAM user calls an API operation to query resources, API Gateway decides whether to allow the API request by checking whether the RAM user has permissions on all the resources that meet the query condition. If the RAM user does not have permissions on all the resources that meet the query condition, API Gateway rejects the API request. Therefore, after you authorize a RAM user by using a tag, the RAM user must specify the tag in the query condition when the user calls an API operation to query resources. For example, the ID of the resource to be queried is specified in the query condition. API Gateway allows the API request only if the resource has the same tag that was used to authorize the RAM user.

3.3 Important note that applies when a RAM user calls API operations to query resources

Assume that you have authorized a RAM user by using a tag. If the RAM user needs to call an API operation to query resources, the RAM user must enable tag-based authorization, namely, set the EnableTagAuth parameter to true in the API request. Only in this way can query results be returned. The EnableTagAuth parameter must be set to true in each request when a RAM user, who is authorized by using a tag, calls the following API operations to query resources:

  • DescribeApiGroups

  • DescribeAppAttributes

3.4 Important note that applies when you authorize a RAM user to query resources

In earlier versions of the RAM console, if you use the following authorization policy to authorize a RAM user to query an API group, information about the API group can be returned. However, in the latest version of the RAM console, the information about the API group will not be returned.

{
     "Effect": "Allow",
     "Action": "apigateway:*",
     "Resource": "acs:apigateway:*:*:apigroup/f0b34d4c55504a34897f7390a24ce253"
}

In the latest version of the RAM console, for a RAM user to query resources, the following adjustments must be made. Note that to authorize a RAM user to create or manage resources, you create authorization policies as you did in earlier versions of the RAM console and do not need to make adjustments.

  1. Specify the Action and Resource elements in the authorization policy to allow the RAM user to query all API operations in all API groups, as shown in the following code snippet:

    {
         "Effect": "Allow",
         "Action": ["apigateway:DescribeApiGroups", "apigateway:DescribeApisForConsole"],
         "Resource": "acs:apigateway:*:*:apigroup/*"
    }
  2. Log on to the RAM console by using your Alibaba Cloud account and add a tag on the resource to be authorized, such as

    depart:dep1

    . Then, specify the tag in the Condition element of the authorization policy, as shown in the following code snippet. In this way, the authorized RAM user can query resources by adding the tag in the query condition.

{
    "Effect": "Allow",
    "Action": "apigateway:*",
     "Resource": "acs:apigateway:*:*:apigroup/*",
     "Condition": {
           "StringEquals": {
                "apigateway:tag/depart": "dep1"
            }
      }
}