Manage policy sets

Policy set overview

A policy set provides the following core functions:

• Organize policies: Group related policies together, for example the policies that manage access to a specific MCP service, so that you can manage and maintain them in one place.

• Enforce access control: After a policy set is associated with an AI Gateway, all agent invocation requests that pass through the gateway are intercepted and evaluated by the policies in the policy set, and an Allow or Deny decision is returned.

  A policy set has the following key attributes:

• Name: Specified when the policy set is created. The name is globally unique and cannot be changed. Use a naming convention that clearly reflects the business purpose, for example app-prod-permissions.

• Policy set ARN: The globally unique resource identifier of the policy set, in the format acs:agentidentity:{region}:{account_id}:policyset/{policy_set_name}.

• Associated gateways: The AI Gateways associated with the policy set. A policy set can be bound to multiple AI Gateways, but an AI Gateway can be bound to only one policy set at a time.

  The typical workflow is as follows: create a policy set, add policies to the policy set, bind the policy set to an AI Gateway in observe mode, verify the policy evaluation results in the AI Gateway logs, and then switch to enforce mode.

Prerequisites

Before you start, take note of the following items:

• Permissions — (Recommended) Attach the AliyunAgentIdentityFullAccess (manage policy sets) and AliyunAPIGFullAccess (bind, unbind, and query AI Gateways) system policies to the RAM user or RAM role that you use.

• AI Gateway — The gateway that you bind must be the same as the gateway that you specify in the policy resource configuration.

• Quotas — The number of policy sets that you can create is limited, and the number of policies that a policy set can contain is limited. For more information, see Limits.

• Allow policies — A policy set must contain at least one policy whose effect is Allow. Otherwise, all requests are denied.

Create a policy set

Create a policy set so that you can add specific policies to it later.

1. Log on to the AgentIdentity console.

2. In the left-side navigation pane, choose Permissions > Policy Sets.

3. Click Create Policy Set.

4. On the Create Policy Set page, enter the policy set name and a description (optional), and then click Create Policy Set.

   Note

   The policy set name cannot be changed after the policy set is created.

   The policy set appears in the policy set list.

Add a policy to a policy set

After you create a policy set, add specific policy rules to it to define the access control logic.

1. In the policy set list, find the target policy set and click its name.

2. On the policy set details page, click Edit Policy Content on the Policy Content tab.

3. If the policy set contains no policies, the editor automatically adds a policy and prefills the policy name. Otherwise, click Add Policy.

4. On the policy editing page, configure the following settings:

   • Policy Name: Prefilled in the format Policy_{xxxxx} by default.

   • Description (optional): The description of the policy.

   • Policy Statement: The policy statement settings are described in the following table.

   Configuration item	Options	Description
   Effect	Allow / Deny	The authorization effect of the policy, which determines whether matching requests are allowed or denied.
   Principal	All Principals, Specified Principal, Workload Identity, OAuth User, Custom User	The subjects to which the policy applies. For details, see Principal options.
   Resource	Specified Gateway Resource	The target AI Gateway resource that the policy controls. After you specify and bind a gateway, all requests that pass through the gateway are intercepted for authorization evaluation.
   Action	All Actions, Specified Actions	The specific MCP service tools that the policy allows or denies. For details, see Action options.
   Condition	Specified Condition (optional)	The additional conditions under which the policy takes effect, configured as key-value pairs. A single policy supports multiple conditions, and the conditions are in a logical AND relationship.

   To use an inverse exclusion condition (unless), switch to the script editor. For more information about unless, see Policy description.

   

5. Click Submit to complete the policy creation.

   For details about the policy structure and syntax, see Policy description.

Bind an AI Gateway to a policy set

The policies in a policy set apply to the live traffic of an AI Gateway only after you bind the policy set to the gateway.

1. In the policy set list, find the target policy set and click its name.

2. On the policy set details page, click the Associated Gateways tab, and then click Bind Gateway.

   

3. In the Bind Gateway panel, configure the following settings:

   • Select Gateway: Select the AI Gateway to which you want to apply this policy set from the gateway list. The gateway must be the same as the gateway that you specified in the policy resource configuration.

   • Enforcement Mode: Select how the policy set works on the gateway.

     • Observe Mode: Only records policy evaluation results and does not intercept any requests. This mode is mainly used to test and verify that policy evaluation results meet expectations. (Recommended) When you apply a policy set to a production environment, set the mode to observe mode first to make sure that the policy changes do not affect your normal business.

     • Enforce Mode: Strictly enforces policy evaluation results. Denied requests are intercepted by the gateway, and the caller receives an error response with status code 403.

     

4. Click Bind Gateway. The binding task automatically creates and binds the associated dependencies, such as gateway services, gateway service policies, and gateway plugins, and completes the binding between the policy set and the gateway.

   

   After the binding is complete, verify that the policies work as expected by using the plugin logs. For more information, see Monitor policy enforcement.

Monitor policy enforcement

After a policy set is bound to an AI Gateway, you can monitor policy enforcement through the logs of the AgentIdentity Authorization plugin on the AI Gateway, for example to confirm whether a request hit the expected policy and to check the final authorization decision. The typical use cases of these logs are:

• In observe mode: Before you switch to enforce mode, use the logs to compare the actual evaluation results with the expected results and confirm that the policy changes do not affect your normal business.

• In enforce mode: Locate intercepted requests, analyze the denial reasons, and troubleshoot access exceptions or security events.

module:wasm and cluster_id:<ai-gateway-instance-id> and (content:agent-identity-oauth or content:agent_identity_oauth or plugin_name:agent-identity-oauth) and content:<authz_field>

{
  "authz_observe_allow": {
    "allow": true,
    "costMs": 198,
    "decidingPolicySetArn": "acs:agentidentity:cn-beijing:173305794806****:policyset/<policy-set-name>",
    "enforcementMode": "LOG_ONLY",
    "reasons": ["<policy-name-that-allows-access>"],
    "requestId": "3D53F4DE-810C-5E38-8055-4FB4CC15****"
  }
}

{
  "authz_observe_deny": {
    "allow": false,
    "costMs": 129,
    "decidingPolicySetArn": "acs:agentidentity:cn-beijing:173305794806****:policyset/<policy-set-name>",
    "enforcementMode": "LOG_ONLY",
    "reasons": [],
    "requestId": "ACB16D26-6500-5E5B-966E-659345C2****"
  }
}

{
  "authz_trace_deny": {
    "allow": false,
    "costMs": 154,
    "decidingPolicySetArn": "acs:agentidentity:cn-beijing:173305794806****:policyset/<policy-set-name>",
    "enforcementMode": "ENFORCE",
    "reasons": [],
    "requestId": "A7FC6D61-A922-5AEC-873C-6951F81E****"
  }
}

Unbind an AI Gateway

Before you delete a policy set or replace the policy set of a gateway, unbind the gateway first.

1. In the policy set list, find the target policy set that is bound to a gateway and click its name.

2. On the policy set details page, click the Associated Gateways tab.

3. In the list of associated gateways, find the gateway that you want to unbind and click Unbind Gateway in the Actions column.

   

4. In the confirmation dialog box, enter the gateway ARN and then click Unbind Gateway. The unbinding task completes the unbinding between the policy set and the gateway.

   

Delete a policy set

Delete a policy set that is no longer needed.

Before you delete a policy set, make sure that the following conditions are met:

• The policy set is unbound from all AI Gateways.

• The policy set contains no policies.

1. In the policy set list, find the target policy set.

2. Click Delete Policy Set in the Actions column.

3. In the confirmation dialog box that appears, enter the policy set name and then click Delete Policy Set.

   The policy set is removed from the policy set list.

References

• Fine-grained control of Agent permissions

• Policy description