Agent Permissions Overview

Core Concepts

When an AI Agent calls various tools, such as MCP services, unauthorized access or risky operations (for example, deleting critical data) can occur. The permissions feature of Agent Identity lets you configure fine-grained policies. It performs security reviews and access control for every outbound call initiated by an Agent to ensure operational compliance.

The permissions feature involves the following core concepts:

• Policy: Based on the Cedar policy language, a policy defines "who (principal) can (or cannot) perform what operation on what resource under what conditions".

• AI Gateway: The unified entry point for all MCP services and the enforcement point for Agent access policies. The AI Gateway intercepts every tool calling request from an Agent and performs permission evaluation.

• Policy Set: A collection of one or more policies. After you associate a policy set with an AI Gateway, the policies apply to all MCP services under that gateway.

Policy Structure

A complete policy consists of three parts: Effect, Scope, and Condition. Scope defines the policy's boundaries and can be divided into three parts: Principal, Action, and Resource.

// 1. Effect: permit or forbid
permit (
  // 2. Scope: Defines the principal, action, and resource to which the policy applies
  principal is AgentIdentity::OAuthUser,
  action == AIGateway::Action::"mcp-servers.order-service.create-order",
  resource == AIGateway::Gateway::"acs:apig:cn-beijing:{account_id}:gateway/gw-abc..."
)
// 3. Conditions: Fine-grained filtering based on attributes or context
when { context.input.amount >= 1000 && ip(context.sourceIp).isInRange(ip("192.168.1.0/24")) };

Authorization Flow

After you configure a policy set and attach it to an AI Gateway, every call through the AI Gateway undergoes authorization evaluation. For example, when an Agent calls an MCP service, the authorization flow is as follows:

1. Agent initiates a call request: The Agent sends an MCP tool calling request to the AI Gateway. The request includes two parts:

   • Workload Access Token: The Agent automatically obtains a workload access token through the Agent Identity SDK. This token is included in the Authorization request header. For example, in scenarios where a user is involved and has logged on through an Identity Provider (IdP), the Workload Access Token includes both workload identity and user information.

     • User information comes from the JSON Web Token (JWT) issued by the IdP (also known as an Id Token), as shown below:

       {
         "aud": "404590186759221****",
         "sub": "iiCsOvhjNZX/hK0x1jl9****",
         "upn": "test-user@xxxx.onaliyun.com",
         "iss": "https://oauth.aliyun.com",
         "name": "test-user"
       }

     • Workload identity information (ARN):

       acs:agentidentity:cn-beijing:{account_id}:workloadidentitydirectory/default/workloadidentity/{workload_identity_name}

   • MCP request body. For example:

     {
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "get_ticket_details",
         "arguments": {
           "ticket_id": "T-2026001"
         }
       }
     }

2. Gateway intercepts the request: The AI Gateway, as the unified entry point, intercepts the request.

3. Constructs an authorization request: The Agent Identity gateway plugin extracts information from the Agent request and constructs an authorization request to send to the Cedar policy evaluation engine. This request contains four elements (P, A, R, C):

   • P (Principal): The gateway parses the Workload Access Token in the request header, extracts the user identity from the token, and constructs a principal that the engine can recognize. For example: AgentIdentity::OAuthUser::"iiCsOvhjNZX/hK0x1jl9****". The principal ID iiCsOvhjNZX/hK0x1jl9**** is the sub field in the user's JWT, which uniquely identifies the user.

   • A (Action): Constructs an action based on the called MCP service and tool name. For example: AIGateway::Action::"mcp-servers.incident-service.create_ticket".

   • R (Resource): Uses the current AI Gateway's unique identifier as the resource. For example: AIGateway::Gateway::"acs:apig:cn-hangzhou:123...:gateway/gw-abc...".

   • C (Context): Constructs the dynamic information of the request into context, which includes the following:

     • Operation input parameters: Parameters in the MCP request body, such as ticket_id.

     • Environment information: Such as source IP and whether HTTPS is used.

     • User properties: Additional information parsed from the user's JWT, such as user ID, username, and role.

4. Policy evaluation: The permission evaluation engine evaluates all relevant policies by combining the authorization request, the policy set obtained from the gateway, and the entity information parsed from the JWT. It then reaches a unified decision: permit or deny. For example:

   Evaluation Step	Check Content	Result
   Principal Check	Is the principal an OAuth user?	Match
   Action Check	Is the action get_ticket_details?	Match
   Resource Check	Is the resource gateway AIGateway::Gateway::"acs:apig:cn-hangzhou:123...:gateway/gw-abc..."?	Match
   Condition Check	Is the request IP from a trusted CIDR block? Is the user role an O&M engineer?	Match
   Final Result	Permit	Pass

5. Executes the decision:

   • If the decision is permit, the AI Gateway forwards the request to the backend MCP service.

   • If the decision is deny:

     • If the policy set's execution mode is Block Mode, the AI Gateway rejects the request and returns an authorization failed message (403 Forbidden).

     • If the policy set's execution mode is Monitor Mode, the AI Gateway only records the evaluation result and releases the request to the backend MCP service or tool.

Limits

The Agent Identity access policy feature applies only to self-built MCP services. These are MCP services published through Alibaba Cloud AI Gateway. For more information on how to create an MCP service through an AI Gateway, see MCP Service Management.