Troubleshoot IAM Unified Access Policies

This document helps you diagnose and resolve common issues when configuring and enforcing IAM Unified Access Policies (UAPs) for Agent Gateway egress.

Policy enforcement and access failures

This section describes issues with enforcement.

Policy isn't being enforced

Symptom: An agent can access destination tools, MCP servers, or endpoints even though an IAM deny rule or restrictive allow rule was configured to block the access.

Cause: The Agent Gateway authorization extension is running in dry-run mode, or the policy binding scope does not match the target resource. In dry-run mode, access decisions are evaluated and logged for auditing, but requests are never blocked.

Solution:

  1. Switch dry-run mode to enforce mode: In the Google Cloud console, edit your gateway and select Enforce policies under Access Authorization (which writes iamEnforcementMode: "ENFORCED" when creating a gateway, or removes iamEnforcementMode when updating an existing gateway). Or, check your authorization extension configuration file (iap-request-authz-extension.yaml): if iamEnforcementMode is set to "DRY_RUN", remove iamEnforcementMode and re-import the extension using the gcloud CLI:

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
        --source=EXTENSION_FILE.yaml \
        --location=LOCATION
    

    Replace the following:

    • EXTENSION_NAME: the name of your authorization extension
    • EXTENSION_FILE: the filename of your YAML extension configuration
    • LOCATION: the Google Cloud region where your gateway is deployed
  2. Verify gateway authorization policy delegation: Verify that your gateway authorization policy (policyProfile: REQUEST_AUTHZ) is bound to the correct Agent Gateway instance (target.resources).

  3. Check policy binding scope: Verify that the IAM UAP is bound to either the project or the specific Agent Gateway instance that governs the traffic (see List policy bindings).

  4. Inspect rule precedence: When evaluating applicable policies, IAP evaluates deny rules before allow rules:

    • Deny rules override allow rules at the same scope: If both a deny rule and an allow rule apply to the same request, the deny rule takes precedence and blocks access. For example, if a UAP bound to gateway-1 has an allow rule that grants an agent access to a registered MCP server and a deny rule that blocks the deleteRecord tool on that same MCP server, calls to deleteRecord through gateway-1 are blocked.

    • Broader allow rules override restrictive allow rules: Unlike deny rules, a restrictive allow rule doesn't block access if another applicable allow rule grants broader access. If you configured a restrictive allow rule (expecting other requests to be blocked by default) instead of an explicit deny rule, check whether a broader allow rule permits the request across either of the following scopes:

      • Project-level versus gateway-level policy bindings: A UAP bound to the project applies to all Agent Gateway instances in that project. For example, if a policy bound to gateway-1 allows only the getRecord tool on an MCP server, but another policy bound to the project allows all tools on that MCP server without tool conditions, agents routing through gateway-1 can still call every tool on that server.

      • Registry-wide versus per-resource destination rules: Allow rules within or across bound policies are additive. For example, if one allow rule restricts an agent to the getRecord tool on a specific MCP server, but another allow rule grants registry-wide access (destination.is_registered == true) without tool restrictions, the registry-wide allow rule permits the agent to call any tool on that MCP server. To block specific tools or destinations when a broader allow rule exists, use an explicit deny rule.

Enforced policy blocks agent access

Symptom: An agent's egress request fails with an HTTP 403 Forbidden or PERMISSION_DENIED error when Agent Gateway policy enforcement is enabled.

Causes:

  • The agent's identity is not specified in the UAP.

  • The agent's identity wasn't granted the iap.resources.egressViaIAP permission on the destination resource.

  • The exact destination hostname is not registered in Agent Registry

  • The request attributes don't satisfy the Common Expression Language (CEL) conditions in the UAP.

Solution:

  1. Switch to dry-run mode for non-disruptive debugging: While diagnosing the failure, temporarily switch the authorization extension to dry-run mode (iamEnforcementMode: "DRY_RUN") so active agent traffic is not blocked while you inspect audit logs.
  2. Query Cloud Audit Logs: Query Cloud Audit Logs to inspect the exact authorization check and CEL attribute evaluation:

    gcloud

    Run the following gcloud logging read command:

    gcloud logging read \
        'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
        --project=PROJECT_ID \
        --limit=20
    

    Replace PROJECT_ID with your project ID.

    Console

    1. In the Google Cloud console, go to the Logs Explorer page.
    2. Select your project.
    3. In the query editor, enter the following query:
          protoPayload.serviceName="iap.googleapis.com"
          protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
          protoPayload.status.code!=0
          
    4. Click Run query.
    5. Expand the log entry and inspect protoPayload.authorizationInfo to see which target resource URI and permission failed evaluation.
  3. Verify exact hostname matching: Agent Gateway matches destination hostnames exactly. A Google API or third-party service might resolve through multiple hostname variations depending on the SDK version, regional client configuration, or mTLS usage—for example, us-central1-aiplatform.googleapis.com versus us-central1-aiplatform.mtls.googleapis.com versus aiplatform.googleapis.com.

    • If you rely on registered targets, make sure that every exact hostname variation is registered in Agent Registry.
    • If the agent accesses unregistered endpoints, verify that an unregistered endpoint policy grants iap.resources.egressViaIAP for that host and path.
  4. Verify policy binding coverage across scopes: Verify that your UAP is bound to either the project or the specific Agent Gateway instance that handles the traffic, and check whether a rule that grants the iap.resources.egressViaIAP permission exists at one of the three supported destination scopes:

    • Registry-wide: Grants access across all agents, MCP servers, and endpoints in the registry.
    • Per-resource: Grants access to a specific registered MCP server, endpoint, or agent.
    • Unregistered endpoints: Grants access to destinations outside Agent Registry.
    • Note: When listing or searching policy bindings for a target project or Agent Gateway instance, if the returned output is an empty list with no bindings, no IAM UAP is bound to that target.
  5. Verify CEL condition attribute values: Compare the request attribute values logged in Cloud Audit Logs with the literal values in your UAP condition expressions:

    • Case-sensitive string matching: String comparisons in CEL conditions are case-sensitive. Verify that copied or typed values—such as MCP tool names (destination.agent_registry.mcp_server.tool.name), MCP server or agent resource names (destination.agent_registry.mcp_server.name, destination.agent_registry.agent.name), or HTTP methods (destination.unregistered.method)—match the exact casing and spelling in the request.
    • Host and path variations for unregistered destinations: If an egress destination includes a port (for example, destination.unregistered.host with example.com:443), subdomains, or variable URL paths (destination.unregistered.path), an exact equality check (==) fails unless the full string matches. For destination.unregistered.host and destination.unregistered.path, you can use .startsWith(), .endsWith(), or .contains() instead of exact equality (==):
      • Use .startsWith() to filter URL paths by prefix (for example, destination.unregistered.path.startsWith('/v2/process')).
      • Use .endsWith() to grant or deny access to all subdomains that share a specified suffix (for example, destination.unregistered.host.endsWith('.example.com')).

Common UI, gcloud, and REST API error messages

This section describes error messages and how to resolve them.

Policy not found

Error message:

  • Console UI: "The requested policy doesn't exist. Verify that the policy exists for the selected resource."
  • API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

Cause: The UAP ID specified in your update request or policy binding does not exist in the project or location, or was deleted.

Solution: List all available UAPs in your project using gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global to confirm the exact policy ID and location before binding or updating it.

Target binding limit exceeded

Error message:

  • Console UI: "The selected target has reached its limit for access policy bindings. Delete an existing binding before adding a new one."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

Cause: You attempted to attach more policy bindings to a target resource (such as a project or an Agent Gateway instance) than the maximum allowed limit per target.

Solution: Instead of creating a separate UAP and binding for each individual rule, consolidate multiple allow or deny rules into a single UAP bound to the project or Agent Gateway instance. Remove unused bindings using gcloud iam policy-bindings delete.

Policy binding limit exceeded

Error message:

  • Console UI: "The selected policy has reached its limit for bindings. Delete an existing binding before adding a new one."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

Cause: A single UAP is attached to too many distinct target resources across your project.

Solution: Bind the policy at the project scope (//cloudresourcemanager.googleapis.com/projects/<var>PROJECT_ID</var>) so that all Agent Gateway instances in the project enforce it instead of creating separate bindings for each individual Agent Gateway instance. Then, use CEL attribute conditions (such as destination.agent_registry.mcp_server.name) to govern access to individual tools within the policy rules.

Condition limit exceeded

Error message:

  • Console UI: "This policy has reached the maximum number of attribute conditions. Remove some conditions to save your changes."
  • API / gcloud: TOO_MANY_CONDITIONS / Condition limit exceeded for rule in policy.

Cause: A single allow or deny rule contains more Fine-Grained Access Control (FGAC) attribute conditions or complex sub-expressions than supported in a single rule.

Solution: Consolidate attribute checks using CEL logical operators (&&, ||) or set inclusion lookups (in), or split your expressions across multiple rules within the same UAP.

Outdated rule details

Error message:

  • Console UI: "Rule details are outdated. This rule was modified by another user after this page was loaded. Refresh the page to fetch the current details before editing or deleting."
  • API / gcloud: HTTP 412 Precondition Failed / ABORTED due to etag mismatch.

Cause: Another administrator or automated process modified the UAP after you retrieved it, causing your request's etag to differ from the active server state.

Solution: Refresh the Console page to retrieve the active policy details and etag before saving your edits. When using the REST API, perform a GET request first to retrieve the active "etag" value, and include it in your PATCH request payload.

Cannot delete the last rule in a policy

Error message:

  • Console UI: "Cannot delete this rule. The 'Default policy' must contain at least one rule. To remove this rule, delete the policy instead." or "This is the last rule in <policy name>. Deleting it will also delete the policy and permanently remove all associated bindings, which can affect agent access to resources."

Cause: An IAM UAP cannot be saved with zero rules.

Solution: If you want to remove the only rule in a policy, delete the entire policy. Remember that you must delete all policy bindings that reference the policy before you can delete the policy itself.

Custom CEL expression preserved in Advanced tab

Error message:

  • Console UI: "The custom CEL expression could not be converted into standard UI selections. Your expression is preserved in the Advanced tab."

Cause: You entered a complex CEL condition or function in the Condition editor (Advanced tab) that cannot be mapped into the simplified drop-down selectors of the standard condition builder.

Solution: This message is an informational notification. Your custom CEL condition is valid and preserved. Continue making any edits directly inside the Condition editor tab.

Function cannot be called on target attribute

Error message:

  • API / gcloud: Function '<var>FUNCTION_NAME</var>' cannot be called on the target '<var>ATTRIBUTE_NAME</var>' in namespace 'iap.googleapis.com'. (Error code 3 / INVALID_ARGUMENT)

Cause: A policy rule condition uses a CEL function (such as .startsWith(), .endsWith(), or .contains()) on an attribute that does not support that function, or attempts to call string functions on boolean attributes or unsupported fields. In UAPs, string-matching functions are supported only on destination.unregistered.host and destination.unregistered.path.

Solution: Update your CEL condition expression to use only the supported operations for the target attribute:

  • Unregistered host and path attributes (destination.unregistered.host, destination.unregistered.path): use ==, !=, in, .startsWith(), .endsWith(), or .contains().
  • Other string attributes (destination.unregistered.method and destination.agent_registry.* string attributes): use ==, !=, or in.
  • Boolean attributes (for example, destination.is_registered, tool annotations): use logical comparisons (==, !=).

For the complete list of attributes and supported operations, see CEL attributes for UAPs.

Users named in policy do not belong to a permitted customer

Error message:

  • API / gcloud: One or more users named in the policy do not belong to a permitted customer. (Error code 3 / INVALID_ARGUMENT)

Cause: IAM UAPs enforce built-in, non-configurable Domain Restricted Sharing (DRS) by default on principals added to ALLOW rules. One or more principal identities specified in the principals array of an ALLOW rule (such as an agent identity, workload identity, user identity, or service account) does not belong to the same Google Cloud organization as the project where the policy is being created or updated. This built-in check does not depend on organization policy constraints (such as constraints/iam.allowedPolicyMemberDomains or constraints/iam.managed.allowedPolicyMembers) and cannot be disabled.

Solution: Inspect the principals array in the ALLOW rules of your policy configuration file (such as the JSON or YAML file specified with the --details-rules flag in gcloud iam access-policies create or update). Remove any external principals and ensure that all specified principal identities belong to the same Google Cloud organization as your project.

What's next