API Gateway allows you to use Alibaba Cloud Resource Access Management (RAM) to grant different permissions on API operations to different employees in your enterprise. As an API provider, you can create RAM users for employees and grant different permissions on API operations to different employees.

  • A RAM user can manage resources in API Gateway, for example, create, view, or delete an API group, an API operation, or a plug-in. However, the RAM user does not own the resources. Permissions of the RAM user on the resources can be revoked by the relevant Alibaba Cloud account at any time.
  • You can use tag-based authorization to isolate resources for an Alibaba Cloud account and its RAM users.
  • Before you begin, make sure that you have read RAM documentation and API Gateway API Reference.
  • If your business does not require permission management for API operations, skip this topic.

To manage user permissions for API Gateway, log on to the RAM console or call RAM API operations. For more information, see RAM introduction.

Part one: Policy management

An authorization policy describes basic elements of an authorization operation, including the permission effect, authorized resource, allowed action, and authorization condition.

1. System authorization policy

API Gateway provides two built-in system authorization policies: AliyunApiGatewayFullAccess and AliyunApiGatewayReadOnlyAccess. You can log on to the RAM console to view these two policies on the Policies page.
  • AliyunApiGatewayFullAccess: authorizes a RAM user to manage all resources under the relevant Alibaba Cloud account, including API groups, API operations, throttling policies, and applications.
  • AliyunApiGatewayReadOnlyAccess: allows a RAM user to view all resources under the relevant Alibaba Cloud account, including API groups, API operations, throttling policies, and applications. However, the RAM user cannot perform operations on the resources.

2. Custom authorization policy

You can customize finer-grained authorization policies, such as creating a custom authorization policy to allow a specific action or grant permissions on a specific resource. For example, you can create a custom authorization policy to grant the edit permission on the GetUsers operation. To view custom authorization policies that you have created, log on to the RAM console. In the left-side navigation pane, choose Permissions > Policies. For information about how to create, view, modify, or delete a custom authorization policy, see Manage policies.

For more information about authorization policies and how to create a custom authorization policy, see Part two of this topic, Policy elements, and Policy structure and grammar.

Part two: Authorization policy

An authorization policy is a collection of elements that are defined based on the policy structure and syntax and are used to describe the authorization operation. You can attach an authorization policy to a RAM user or a group, so that the user or the group can obtain the specified permission on the specified resource. For information about how to create a custom authorization policy, see Policy elements and Policy structure and grammar.

The following code snippet shows an example of an authorization policy:
{
  "Version": "1",
  "Statement": [
    {
  "Action": "apigateway:Describe*",
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}
		

This authorization policy allows a RAM user to query all resources in API Gateway.

The Action element in an authorization policy must be in the following format:

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

Each value of the Action element must contain the following parts:

  • service-name: the name of an Alibaba Cloud service. In this topic, enter apigateway.
  • action-name: the name of an API operation. You can use a wildcard (*) for the name. For information about API operations that are provided by API Gateway, see the table in Part three.

    "Action": "apigateway:Describe*" indicates that the authorized RAM user can query all resources in API Gateway.

    "Action": "apigateway:*" indicates that the authorized RAM user has all permissions on all resources in API Gateway.

Part three: Resource

A resource is an object on which a RAM user is to be granted permissions. In API Gateway, API groups, throttling policies, and applications are all resources. In each authorization policy, a resource must be specified in the following format:

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

The format contains the following parts:

  • acs: the abbreviation of Alibaba Cloud Service, which indicates the public cloud of Alibaba Cloud.
  • service-name: the name of an Alibaba Cloud service. In this topic, enter apigateway.
  • region: the region where the current authorization policy applies. You can specify this part as a wildcard (*), which indicates that the current authorization policy applies in all regions.
  • account-id: the account ID of the RAM user to be authorized, for example, 1234567890123456. You can specify this part as a wildcard (*), which indicates that the current authorization policy is attached to all RAM users under the current Alibaba Cloud account.
  • relative-id: the description of the resource on which a RAM user is to be granted permissions. You can specify this part as a string that is similar to a file path.

For example, when you create an authorization policy to grant a RAM user permissions on an API group, you can specify the API group in the following format:

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

If you need to authorize all RAM users under the current Alibaba Cloud account to view an API group in all regions, you can specify the API group as shown in the following code snippet:

acs:apigateway:*:*:apigroup/cbd157704e624ab58a204fd3e0b5ad79

The following table describes the action names that you can use when you create authorization policies to manage permissions on API operations of API Gateway. For more information, see Create an API group.

action-name Description Resource
CreateApiGroup Creates an API group. acs:apigateway:$regionid:$accountid:apigroup/*
ModifyApiGroup Modifies an API group. acs:apigateway:$regionid:$accountid:apigroup/$groupId
DeleteApiGroup Deletes an API group. acs:apigateway:$regionid:$accountid:apigroup/$groupId
DescribeApiGroups Queries available API groups. acs:apigateway:$regionid:$accountid:apigroup/*
CreateApi Creates an API operation. acs:apigateway:$regionid:$accountid:apigroup/$groupId
DeployApi Publishes an API operation. acs:apigateway:$regionid:$accountid:apigroup/$groupId
AbolishApi Unpublishes an API operation. acs:apigateway:$regionid:$accountid:apigroup/$groupId
DeleteApi Deletes an API operation. acs:apigateway:$regionid:$accountid:apigroup/$groupId
DescribeApis Queries available API operations. acs:apigateway:$regionid:$accountid:apigroup/*
CreatePlugin Creates a plug-in. acs:apigateway:$regionid:$accountid:plugin/*
ModifyPlugin Modifies a plug-in. acs:apigateway:$regionid:$accountid:plugin/$pluginId
DeletePlugin Deletes a plug-in. acs:apigateway:$regionid:$accountid:plugin/$pluginId
AttachPlugin Binds a plug-in to an API operation. acs:apigateway:$regionid:$accountid:plugin/$pluginId
DetachPlugin Unbinds a plug-in from an API operation. acs:apigateway:$regionid:$accountid:plugin/$pluginId
DescribePluginsByApi Queries plug-ins that are bound to an API operation. acs:apigateway:$regionid:$accountid:plugin/$pluginId
CreateApp Creates an application. acs:apigateway:$regionid:$accountid:app/*
ModifyApp Modifies an application. acs:apigateway:$regionid:$accountid:app/$appId
DeleteApp Deletes an application. acs:apigateway:$regionid:$accountid:app/$appId
DescribeAppAttributes Queries available applications. acs:apigateway:$regionid:$accountid:app/$appId
SetApisAuthorities Authorizes an application to call one or more API operations. acs:apigateway:$regionid:$accountid:apigroup/$groupId
DescribeAuthorizedApps Queries applications that are authorized to call an API operation. acs:apigateway:$regionid:$accountid:apigroup/$groupId
SetVpcAccess Creates a virtual private cloud (VPC) authorization entry. acs:apigateway:$regionid:$accountid:vpcaccess/*
RemoveVpcAccess Deletes a VPC authorization entry. acs:apigateway:$regionid:$accountid:vpcaccess/*
DescribeVpcAccesses Queries available VPC authorization entries. acs:apigateway:$regionid:$accountid:vpcaccess/*
DescribeInstances Queries available dedicated instances. acs:apigateway:$regionid:$accountid:instance/$instanceId

Examples of authorization policies

Authorize a RAM user to query all API operations:

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

Authorize a RAM user to query API operations in all API groups with the `version:v1` tag:

{
	  "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 API operations 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 specific parts as * based on your business requirements.