API Gateway:Reference for API Gateway custom policies

What is a custom policy?

Resource Access Management (RAM) policies are classified into system policies and custom policies. You can manage custom policies based on your business requirements.

• After you create a custom policy, you must attach the policy to a RAM user, RAM user group, or RAM role. This way, the permissions that are specified in the policy can be granted to the principal.

• You can delete a RAM policy that is not attached to a principal. If the RAM policy is attached to a principal, you must detach the RAM policy from the principal before you can delete the RAM policy.

• Custom policies support version control. You can manage custom policy versions based on the version management mechanism provided by RAM.

References

• Create a custom policy

• Modify the document and description of a custom policy

• Delete a custom policy

• Manage policy references

• Manage custom policy versions

Section 1: Policy overview

A policy defines the details of permissions and contains the following basic elements: Effect, Resource, Action, and Condition.

You can create a custom policy to grant finer-grained permissions, such as the permissions for a specific action or on a specific resource. For example, you can create a custom policy to grant the edit permissions on GetUsers. To view a custom policy that you create, perform the following steps: Log on to the RAM console. In the left-side navigation pane, choose Permissions > Policies. On the page that appears, select Custom Policy from the Policy Type drop-down list and find the policy.

Section 2: Policy syntax

A policy defines a set of permissions based on a specific syntax. You can attach a policy to a user or a group of users to grant them specific permissions on specific resources.

{
  "Version": "1",
  "Statement": [
    {
  "Action": "apigateway:Describe*",
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
                

The preceding example shows a policy that allows a Resource Access Management (RAM) user to query all resources in API Gateway.

The Action element describes one or more API operations. The parameters in the Action element must be specified in the following format:

 "Action":"<service-name>:<action-name>"

In the preceding code:

• service-name: the name of an Alibaba Cloud service. In this example, apigateway is specified.

• action-name: the name of an API operation. You can use the wildcard character (*) for the name. For more information about API operations that are provided by API Gateway, see the table in "Section 3" of this topic.

  If you set "Action" to "apigateway:Describe*", the authorized RAM user has the permissions to query all resources in API Gateway.

  If you set "Action" to "apigateway:*", the authorized RAM user has the permissions to manage all resources in API Gateway.

Section 3: Resource

The Resource element specifies one or more objects that the statement covers. In API Gateway, you can specify an API group, throttling policy, and application in the Resource element. The parameters in the Resource element must be specified in the following format:

acs:<service-name>:<region>:<account-id>:<relative-id>

In the preceding code:

• acs: indicates that the business scope of the service belongs to Alibaba Cloud public cloud.

• service-name: the name of an Alibaba Cloud service. In this example, apigateway is specified.

• region: the region where the policy applies. You can set this parameter to a wildcard character (*), which indicates that the policy applies in all regions.

• account-id: the ID of the account, such as 123456789012****. This parameter supports wildcard characters (*).

• relative-id: the description of the resource on which you want to grant the permissions to a RAM user. You can specify this parameter in the format that is similar to a file path.

Format:

acs:apigateway:$regionid:$accountid:apigroup/$groupId

Example:

acs:apigateway:*:*:apigroup/cbd157704e624ab58a204fd3e0b5ad79

The following table describes the API operations that you can specify for the action-name parameter when you create policies to manage the permissions on resources in API Gateway. For more information, see "API Gateway API Reference".

Examples

Authorize a RAM user to query all APIs:

{
          "Version": "1",
          "Statement": [
            {
                      "Action": "apigateway:Describe*",
                      "Resource":"acs:apigateway:$regionid:$accountid:apigroup/*",
                      "Effect": "Allow"
            }
          ]
}                        

Authorize a RAM user to query all API groups to which the `version:v1` tag is attached:

{
	  "Version": "1",
	  "Statement": [
	    {
      		"Action": "apigateway:Describe*",
	      	"Resource":"acs:apigateway:$regionid:$accountid:apigroup/*",
	      	"Effect": "Allow", 
                 "Condition": {
                        "StringEquals": {
                             "apigateway:tag/version": "v1"
                        }
                 }
             }
	  ]
}			

Authorize a RAM user to manage all APIs in an API group:

{
          "Version": "1",
          "Statement": [
            {
                      "Action": "apigateway:*",
                      "Resource": [
                              "acs:apigateway:$regionid:$accountid:apigroup/$groupId",
                              "acs:apigateway:$regionid:$accountid:app/$appId",
                              "acs:apigateway:$regionid:$accountid:vpcaccess/*"
                      ],
                      "Effect": "Allow"
            }
          ]
}

Note: In the preceding examples, you can specify wildcard characters (*) for variables based on your business requirements.