Manage IAM Unified Access Policies

You can create, list, view, update, and delete IAM Unified Access Policies (UAPs) and policy bindings using the Google Cloud console, the gcloud CLI, or the REST API.

Agent Gateway uses Identity-Aware Proxy (IAP) to enforce these egress policies across your agents, MCP servers, and endpoints. For an overview of how policies work, see IAM UAPs overview. For detailed rule examples and CEL attributes, see Create IAM UAPs.

Required roles

To get the permissions that you need to manage UAPs and policy bindings, ask your administrator to grant you the following IAM roles on your project:

View UAPs and bindings: Access Policy Viewer (roles/iam.accessPolicyViewer)
Create, update, and delete UAPs and bindings: Access Policy Admin (roles/iam.accessPolicyAdmin)
Bind policies to a project: Project IAM Admin (roles/resourcemanager.projectIamAdmin)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Create a UAP

A UAP contains one or more allow or deny rules. Before a policy takes effect, you must bind it to a target resource.

For more information about creating UAPs, see Create IAM UAPs.

Console

In the Google Cloud console, go to the Policies page:

Go to Policies
In the project selector, select the project that contains the agent gateways that will use the UAP.
To add an IAM UAP for Agent Gateway egress, click Create.
In the Policy details pane, do the following:
1. Click the Policy field.
2. In the drop-down list, select Create new policy.
3. In the Policy name field, enter a descriptive name for the policy.
4. In Add Rules, configure your allow or deny rules and CEL conditions. For UAP configuration steps and examples, see Create IAM UAPs.
5. To save the rule, click Create.

gcloud

To create a UAP using the gcloud CLI, define your policy rules in a JSON file and run the create command:

gcloud iam access-policies create POLICY_NAME \
    --details-rules=POLICY_FILE \
    --project=PROJECT_ID \
    --location=global

Replace the following:

POLICY_NAME: the name of the policy
POLICY_FILE: the path to the policy file—for example: my-policy.json
PROJECT_ID: the project ID that contains the policy

API

To create a UAP using the REST API, make a POST request to the accessPolicies endpoint:

curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies?accessPolicyId=POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "details": {
    "rules": [
      {
        "description": "RULE_DESCRIPTION",
        "effect": "ALLOW",
        "principals": [
          "principal://agents.global.proj-PROJECT_NUMBER.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_NAME"
        ],
        "operation": {
          "permissions": [
            "iap.resources.egressViaIAP"
          ]
        },
        "conditions": {
          "iap.googleapis.com": {
            "expression": "CEL_EXPRESSION"
          }
        }
      }
    ]
  }
}'

Replace the following:

PROJECT_ID: your project ID
POLICY_NAME: the ID for the new policy
PROJECT_NUMBER: the project number
LOCATION: the agent location
AGENT_NAME: the source agent ID
CEL_EXPRESSION: your CEL condition expression

Bind a policy to a target resource

To enforce a UAP, bind it to a target resource scope, such as a project or an Agent Gateway instance.

Console

When you save a policy, it is automatically bound to the project.

gcloud

To bind a UAP to a target resource using the gcloud CLI, run the following command:

gcloud iam policy-bindings create BINDING_NAME \
    --policy="projects/PROJECT_ID/locations/global/accessPolicies/POLICY_NAME" \
    --target-resource="TARGET_RESOURCE" \
    --project=PROJECT_ID \
    --location=global

Replace the following:

BINDING_NAME: the name for your policy binding
PROJECT_ID: your Google Cloud project ID
POLICY_NAME: the name of your access policy
TARGET_RESOURCE: the full resource URI for the project, formatted as follows:
```
    //cloudresourcemanager.googleapis.com/projects/PROJECT_ID
    
```

API

To bind a UAP to a target resource using the REST API, make a POST request to the policyBindings endpoint:

curl -X POST \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/policyBindings?policyBindingId=BINDING_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "policy": "projects/PROJECT_ID/locations/global/accessPolicies/POLICY_NAME",
  "target": {
    "resource": "TARGET_RESOURCE"
  }
}'

Replace the following:

PROJECT_ID: your project ID
BINDING_NAME: a name for your policy binding
POLICY_NAME: the name of the UAP
TARGET_RESOURCE: the full resource URI for the project, formatted as follows: //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

List policies and policy bindings

You can list all UAPs in your project or list all policy bindings attached to a target resource.

List UAPs

Console

In the Google Cloud console, go to the Policies page.
All UAPs created in your project appear in the list in the Unified Access Policies tab.

gcloud

To list UAPs in your project, run the following command:

gcloud iam access-policies list \
  --project=PROJECT_ID \
  --location=global

API

To list UAPs using the REST API, make a GET request to the accessPolicies endpoint:

curl -X GET \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies" \
-H "Authorization: Bearer $(gcloud auth print-access-token)"

List policy bindings

Console

Because policies that are managed through the console are automatically bound to the project, you must use the gcloud CLI or the REST API to view policy bindings.

gcloud

To list policy bindings in your project, run the following command:

gcloud iam policy-bindings list \
  --project=PROJECT_ID \
  --location=global

To filter policy bindings by a specific target resource, specify the --target-resource flag:

gcloud iam policy-bindings list \
  --target-resource="TARGET_RESOURCE" \
  --project=PROJECT_ID \
  --location=global

API

To list policy bindings using the REST API, make a GET request to the policyBindings endpoint:

curl -X GET \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/policyBindings" \
-H "Authorization: Bearer $(gcloud auth print-access-token)"

Describe a policy or policy binding

You can retrieve the detailed configuration and rules of a specific UAP or policy binding.

Describe a UAP

Console

In the Google Cloud console, go to the Policies page:

Go to Policies
In the project selector, select the project that contains the agent gateways that will use the UAP.
In the Agent policies table in the UAPs tab, locate the policy that you want to describe.
In the row for the policy, click More actions, and then click View rule.

gcloud

To describe a specific UAP, run the following command:

gcloud iam access-policies describe POLICY_NAME \
  --project=PROJECT_ID \
  --location=global

API

To retrieve a specific UAP using the REST API, make a GET request:

curl -X GET \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies/POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)"

Describe a policy binding

Console

Because policies that are managed through the console are automatically bound to the project, you must use the gcloud CLI or the REST API to view policy bindings.

gcloud

To describe a specific policy binding, run the following command:

gcloud iam policy-bindings describe BINDING_NAME \
  --project=PROJECT_ID \
  --location=global

API

To retrieve a specific policy binding using the REST API, make a GET request:

curl -X GET \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/policyBindings/BINDING_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)"

Update policies and policy bindings

You can update the rules inside an existing UAP or update the target or policy referenced by a policy binding.

Update a UAP

Console

In the Google Cloud console, go to the Policies page:

Go to Policies
In the project selector, select the project that contains the agent gateways that will use the UAP.
In the Agent policies table in the UAPs tab, locate the policy row that you want to edit.
Click More actions, and then click Edit rule.
Modify the rules, effect, principals, or CEL conditions.
Click Save.

gcloud

To update an existing UAP using the gcloud CLI, save your modified rules to a JSON file and run the following command:

gcloud iam access-policies update POLICY_NAME \
  --details-rules=POLICY_FILE.json \
  --project=PROJECT_ID \
  --location=global

API

To update a UAP using the REST API, make a PATCH request to the UAP endpoint:

curl -X PATCH \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies/POLICY_NAME?updateMask=details" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "details": {
    "rules": [
      {
        "description": "RULE_DESCRIPTION",
        "effect": "ALLOW",
        "principals": [
          "principal://agents.global.proj-PROJECT_NUMBER.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_NAME"
        ],
        "operation": {
          "permissions": [
            "iap.resources.egressViaIAP"
          ]
        }
      }
    ]
  }
}'

Update a policy binding

Console

To update a policy binding, you must use the gcloud CLI or the REST API.

gcloud

To update a policy binding to reference a different policy or target, run the following command:

gcloud iam policy-bindings update BINDING_NAME \
  --policy="projects/PROJECT_ID/locations/global/accessPolicies/NEW_POLICY_NAME" \
  --project=PROJECT_ID \
  --location=global

API

To update a policy binding using the REST API, make a PATCH request:

curl -X PATCH \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/policyBindings/BINDING_NAME?updateMask=policy" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
  "policy": "projects/PROJECT_ID/locations/global/accessPolicies/NEW_POLICY_NAME"
}'

Delete policies and policy bindings

Delete a policy binding

Console

To delete a policy binding, you must use the gcloud CLI or the REST API.

gcloud

To delete a policy binding, run the following command:

gcloud iam policy-bindings delete BINDING_NAME \
  --project=PROJECT_ID \
  --location=global

API

To delete a policy binding using the REST API, make a DELETE request:

curl -X DELETE \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/policyBindings/BINDING_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)"

Delete a UAP

Console

To delete a UAP, you must delete all of the rules in the policy.

In the Google Cloud console, go to the Policies page:

Go to Policies
In the project selector, select the project that contains the agent gateways that will use the UAP.
In the Agent Policies table of the Unified Access Policies tab, filter Filter or locate the policy that you want to delete.
Click More actions, and then click Delete rule.

gcloud

To delete a UAP after deleting its bindings, run the following command:

gcloud iam access-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --location=global

API

To delete a UAP using the REST API, make a DELETE request:

curl -X DELETE \
"https://iam.googleapis.com/v3beta/projects/PROJECT_ID/locations/global/accessPolicies/POLICY_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)"

What's next

Overview

Manage IAM Unified Access Policies Stay organized with collections Save and categorize content based on your preferences.

Required roles

Create a UAP

Console

gcloud

API

Bind a policy to a target resource

Console

gcloud

API

List policies and policy bindings

List UAPs

Console

gcloud

API

List policy bindings

Console

gcloud

API

Describe a policy or policy binding

Describe a UAP

Console

gcloud

API

Describe a policy binding

Console

gcloud

API

Update policies and policy bindings

Update a UAP

Console

gcloud

API

Update a policy binding

Console

gcloud

API

Delete policies and policy bindings

Delete a policy binding

Console

gcloud

API

Delete a UAP

Console

gcloud

API

What's next

Agent Gateway overview

Configure content and business policies

Test policies

Manage IAM Unified Access Policies