All Products
Search
Document Center

API Gateway:Use RAM to manage the permissions on API resources

Last Updated:Oct 26, 2023

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

  • A RAM user can manage resources in API Gateway. For example, a RAM user can view, create, or delete API groups, APIs, or plug-ins. However, the RAM user does not own the resources. You can use your Alibaba Cloud account to revoke the permissions on the resources from the RAM user at any time.

  • You can use tag-based authorization to isolate resources between your Alibaba Cloud account and RAM users.

  • Before you use RAM to manage the permissions on API resources, make sure that you have read RAM documentation and API Gateway API Reference.

  • If your business does not require permission management for API resources, skip this topic.

Section 1: Policy overview

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

1. System policy

API Gateway provides the following built-in system policies: AliyunApiGatewayFullAccess and AliyunApiGatewayReadOnlyAccess. You can log on to the RAM console to view these policies on the Policies page.

  • AliyunApiGatewayFullAccess: authorizes a RAM user to manage all API Gateway resources within the relevant Alibaba Cloud account, such as API groups, APIs, throttling policies, and applications.

  • AliyunApiGatewayReadOnlyAccess: allows a RAM user to view all API Gateway resources within the relevant Alibaba Cloud account, such as API groups, APIs, throttling policies, and applications. However, the RAM user cannot manage the resources.

2. Custom policy

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.

Example:

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

The preceding example shows a policy that allows a 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>"

Parameters:

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

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>

Parameters:

  • 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 the wildcard character (*), which indicates that the policy applies in all regions.

  • account-id: the ID of the account, such as 123456789012****. You can set this parameter to the wildcard character (*).

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

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 API groups.

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

CreateApi

Creates an API.

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

DeployApi

Publishes an API.

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

AbolishApi

Unpublishes an API.

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

DeleteApi

Deletes an API.

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

DescribeApis

Queries APIs.

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.

acs:apigateway:$regionid:$accountid:plugin/$pluginId

DetachPlugin

Unbinds a plug-in from an API.

acs:apigateway:$regionid:$accountid:plugin/$pluginId

DescribePluginsByApi

Queries plug-ins that are bound to an API.

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 applications.

acs:apigateway:$regionid:$accountid:app/$appId

SetApisAuthorities

Authorizes an application to call APIs.

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

DescribeAuthorizedApps

Queries applications that are authorized to call an API.

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

SetVpcAccess

Creates a virtual private cloud (VPC) authorization.

acs:apigateway:$regionid:$accountid:vpcaccess/*

RemoveVpcAccess

Deletes a VPC authorization.

acs:apigateway:$regionid:$accountid:vpcaccess/*

DescribeVpcAccesses

Queries VPC authorizations.

acs:apigateway:$regionid:$accountid:vpcaccess/*

DescribeInstances

Queries dedicated instances.

acs:apigateway:$regionid:$accountid:instance/$instanceId

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 the wildcard character (*) for variables based on your business requirements.