Control access to Memory Bank with IAM Conditions

By default, memory Identity and Access Management permissions are at the project-level. This document describes how to use IAM Conditions to control more granular access to Vertex AI Agent Engine Memory Bank resources.

Overview

IAM Conditions let you grant access to memory and memory revision resources only if specified conditions are met. You can control access to memories based on the scope field within a memory resource using the API attribute "aiplatform.googleapis.com/memoryScope" with an expression written in Common Expression Language. Scope is an arbitrary dictionary that is provided when creating or generating memories, like {'user_id': '123'}, that lets you organize which memories belong to which group.

These conditional Identity and Access Management policies are created at the project level and apply to all memories within a project. You can apply IAM conditions to all kinds of principals, including users of your project and service accounts.

IAM Conditions are useful for granting Identity and Access Management (IAM) permissions to many related Memory Bank resources simultaneously, including those that don't exist yet. You can restrict access to your memories and revisions so that a user can only access their own information, or so developers can only view certain Memory Bank resources without special permission grants.

Before you begin

To set up conditional IAM policies for memories and memory revisions, do the following:

Review IAM Conditions: Familiarize yourself with the IAM Conditions overview.
Determine necessary roles: Identify which specialized Memory Bank IAM roles are appropriate for your use case to ensure the principle of least privilege.
Identify affected principals: Identify who in your organization should receive which permissions. For example, consider the following:
- Whether developers should be able to see all memories.
- Whether project administrators should be able to see all memories.
- Whether certain agent identities can only access certain memories.
Grant IAM roles: Ensure you have the required roles that contain the necessary permissions you need to perform the tasks in this document.
To get the permissions that you need to apply IAM Conditions to Vertex AI Agent Engine Memory Bank resources, ask your administrator to grant you the following IAM roles:
- For projects: Project IAM Admin (roles/resourcemanager.projectIamAdmin)
For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to apply IAM Conditions to Vertex AI Agent Engine Memory Bank resources. To see the exact permissions that are required, expand the Required permissions section:
Required permissions

The following permissions are required to apply IAM Conditions to Vertex AI Agent Engine Memory Bank resources:
- Set conditional IAM access at the project level: resourcemanager.projects.setIamPolicy
You might also be able to get these permissions with custom roles or other predefined roles.
If you plan to use IAM Conditions across your organization, you also need permissions to manage organization policies.

Creating conditional access for memories

Conditional access to memories is granted by adding a condition to an IAM policy binding at the project level. The condition uses the api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) function to inspect the scope map of a memory resource. You define scope when you create or generate a memory.

For a detailed guide on creating IAM policies with conditions, see Conditions in allow policies.

Best practices for scope-level permissions

When you build conditions for Memory Bank, use the following best practices:

Use specialized Memory Bank roles: Memory Bank IAM Conditions should only be used for roles that apply to memories and memory revisions. You can use specialized roles such as aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor, and aiplatform.googleapis.com/memoryUser to prevent overly permissive access. See Specialized Memory Bank IAM Roles roles for more details.
Use positive conditions: We recommend using positive conditions (such as checks for equality or the presence of key-value pairs) aiplatform.googleapis.com/memoryScope for greater accuracy. Since unsupported types and services are represented by an empty scope, negative conditions (such as checks for inequality) might inadvertently match a wide range of resources, which can be overly permissive and allow for unexpected permission granting.
Shorten conditions if possible: We recommend using the shortest and simplest logic within your IAM condition expressions, especially if you plan on having a large amount of conditions. IAM allow policies have a size limitation, and simplifying conditions prevents running into these IAM limitations. See Limitations for more details. For example, you can omit checking the presence of a key in the expression 'user_id' in "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' as it evaluates to the same result as the shorter statement api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'.

Specialized Memory Bank IAM roles

It is critical to prevent overly permissive IAM policies when using IAM Conditions. The following table lists specialized roles that you can use when granting conditional IAM roles for Memory Bank APIs:

Role Name	Description	Included Permissions
`aiplatform.googleapis.com/memoryViewer`	Grants read-only access to memories and memory revisions.	`aiplatform.googleapis.com/memories.get` `aiplatform.googleapis.com/memories.list` `aiplatform.googleapis.com/memories.retrieve` `aiplatform.googleapis.com/memoryRevisions.list` `aiplatform.googleapis.com/memoryRevisions.get`
`aiplatform.googleapis.com/memoryEditor`	Grants write and generate access to memories and rollback access to memory revisions.	`aiplatform.googleapis.com/memories.create` `aiplatform.googleapis.com/memories.update` `aiplatform.googleapis.com/memories.delete` `aiplatform.googleapis.com/memories.generate` `aiplatform.googleapis.com/memoryRevisions.rollback`
`aiplatform.googleapis.com/memoryUser`	Grants full access to memories and revisions, including all viewer and editor permissions.	Includes all permissions of both `memoryEditor` and `memoryViewer`.

Using IAM Conditions with Memory Bank

This section covers the following examples of using IAM Conditions with Memory Bank:

Grant read access to memories with exact scope match.
Grant write access to memories with scope containing a specific key-value pair.
Grant full access to memories with scope containing specific keys.
Grant full access to memories with scope containing a specific prefix.
Grant full access to memories with scope of key with a set of allowed values.

Grant read access to memories with exact scope match

The following condition grants the individual userA@gmail.com view access only to memories that have the exact scope {"userId": "userA"}.

This means that the member has the ability to get and retrieve memories, along with listing and getting those memories' revisions, as long as the scope is exactly {"userId": "userA"}. The user doesn't have access to memories with scope such as {'userId': 'userA', 'source': 'ADK'}.

{
  "members": ["user:userA@gmail.com"],
  "role": "roles/aiplatform.memoryViewer",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) == {'userId': 'userA'}"
  }
}

Grant write access to memories with scope containing a specific key-value pair

The following condition grants the individual developerA@corp.com edit access to any memories that contain the key-value pair 'userId': 'userA'.

This means that the user has the ability to create, update, delete, and generate memories, and create and rollback those memories' revisions, with scopes such as {'userId': 'userA'} and {'userId': 'userA', 'source': 'ADK'}.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.memoryEditor",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] == 'userA'"
  }
}

Grant full access to memories with scope containing specific keys

The following condition grants the group group:engineering@corp.com user (viewer and editor) access to memories that have the key 'admin_override' or 'public_access_flag'.

This means members of the group have full read and write access to memories with scopes such as {'admin_override': 'true'}, {'admin_override': 'true', 'public_access_flag': 'false'}, and {'userId': 'userA', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "('admin_override' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {})) || ('public_access_flag' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}))"
  }
}

Grant full access to memories with scope containing a specific prefix

The following condition grants the group group:engineering@corp.com user (viewer and editor) access to memories that have the key 'userId' with value starting with 'user'.You can use 'startsWith' for prefix checking and 'endsWith' for suffix checking.

This means members of the group have full read and write access to memories with scopes such as {'userId': 'userA'}, {'userId': 'userB', 'public_access_flag': 'false'}.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'].startsWith('user')"
  }
}

Grant full access to memories with scope of key with a set of allowed values

The following condition grants the group group:engineering@corp.com user (viewer and editor) access to memories that have the key 'userId' with values of either 'userA' or 'userB'.