Controlla l'accesso a Memory Bank con le condizioni IAM

Memory Bank ti consente di controllare l'accesso alle risorse di memoria e revisione della memoria in base ai relativi attributi di ambito. Puoi utilizzare le condizioni IAM per definire controlli dell'accesso granulari, ad esempio limitare l'accesso a utenti o gruppi specifici in base a criteri definiti nel linguaggio Common Expression Language.

Questo documento descrive come creare e applicare policy di accesso condizionale per i ricordi e le revisioni nel tuo progetto.

Per informazioni generali sulle autorizzazioni, consulta Esaminare i ruoli necessari.

Panoramica

Le condizioni IAM consentono di concedere l'accesso alle risorse di memoria e revisione della memoria solo se sono soddisfatte le condizioni specificate. Puoi controllare l'accesso ai ricordi in base al campo scope all'interno di una risorsa di ricordi utilizzando l'attributo API "aiplatform.googleapis.com/memoryScope" con un'espressione scritta in Common Expression Language. L'ambito è un dizionario arbitrario fornito durante la creazione o la generazione di ricordi, come {'user_id': '123'}, che ti consente di organizzare i ricordi in base al gruppo di appartenenza.

Questi criteri Identity and Access Management condizionali vengono creati a livello di progetto e si applicano a tutte le memorie all'interno di un progetto. Puoi applicare le condizioni IAM a tutti i tipi di entità, inclusi gli utenti del tuo progetto e i service account.

Le condizioni IAM sono utili per concedere autorizzazioni Identity and Access Management (IAM) a molte risorse Memory Bank correlate contemporaneamente, incluse quelle che non esistono ancora. Puoi limitare l'accesso ai tuoi ricordi e alle tue revisioni in modo che un utente possa accedere solo alle proprie informazioni o in modo che gli sviluppatori possano visualizzare solo determinate risorse di Memory Bank senza concessioni di autorizzazioni speciali.

Prima di iniziare

Per configurare le policy IAM condizionali per i ricordi e le revisioni dei ricordi:

• Esamina le condizioni IAM: acquisisci familiarità con la panoramica delle condizioni IAM.
• Determina i ruoli necessari: identifica i ruoli IAM specializzati di Memory Bank appropriati per il tuo caso d'uso per garantire il principio del privilegio minimo.

• Identifica le entità interessate: identifica chi nella tua organizzazione deve ricevere quali autorizzazioni. Ad esempio, considera quanto segue:

  • Se gli sviluppatori devono essere in grado di vedere tutti i ricordi.
  • Se gli amministratori del progetto devono essere in grado di vedere tutti i ricordi.
  • Se determinate identità di agenti possono accedere solo a determinati ricordi.
• Concedi ruoli IAM: assicurati di disporre dei ruoli richiesti che contengono le autorizzazioni necessarie per eseguire le attività descritte in questo documento.

  Per ottenere le autorizzazioni necessarie per applicare le condizioni IAM alle risorse del Memory Bank di Agent Platform, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Per i progetti: Amministratore IAM progetto (`roles/resourcemanager.projectIamAdmin`)

  Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

  Questi ruoli predefiniti contengono le autorizzazioni necessarie per applicare le condizioni IAM alle risorse del Memory Bank di Agent Platform. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

  Autorizzazioni obbligatorie

  Per applicare le condizioni IAM alle risorse di Agent Platform Memory Bank sono necessarie le seguenti autorizzazioni:

  • Imposta l'accesso IAM condizionale a livello di progetto: `resourcemanager.projects.setIamPolicy`

  Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

  Se prevedi di utilizzare le condizioni IAM in tutta l'organizzazione, devi anche disporre delle autorizzazioni per gestire i criteri dell'organizzazione.

Creazione dell'accesso condizionale per i ricordi

L'accesso condizionale ai ricordi viene concesso aggiungendo una condizione a un'associazione di policy IAM a livello di progetto. La condizione utilizza la funzione api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) per ispezionare la mappa degli ambiti di una risorsa di memoria. Definisci l'ambito quando crei o generi un ricordo.

Per una guida dettagliata alla creazione di policy IAM con condizioni, consulta Condizioni nelle policy di autorizzazione.

Per concedere un singolo ruolo a un'entità:

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Memory Access Condition"
    description = "IAM condition for Memory Bank"
    expression  = "CONDITION"
  }
}

Best practice per le autorizzazioni a livello di ambito

Quando crei le condizioni per Memory Bank, utilizza le seguenti best practice:

1. Utilizza ruoli Memory Bank specializzati: le condizioni IAM di Memory Bank devono essere utilizzate solo per i ruoli che si applicano ai ricordi e alle revisioni dei ricordi. Puoi utilizzare ruoli specializzati come aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryEditor e aiplatform.googleapis.com/memoryUser per impedire l'accesso eccessivamente permissivo. Per maggiori dettagli, consulta i ruoli IAM di Specialized Memory Bank.

2. Utilizza condizioni positive: ti consigliamo di utilizzare condizioni positive (ad esempio controlli di uguaglianza o la presenza di coppie chiave-valore) su aiplatform.googleapis.com/memoryScope per una maggiore precisione. Poiché i tipi e i servizi non supportati sono rappresentati da un ambito vuoto, le condizioni negative (come i controlli di disuguaglianza) potrebbero corrispondere inavvertitamente a un'ampia gamma di risorse, il che può essere eccessivamente permissivo e consentire la concessione imprevista di autorizzazioni.

3. Abbrevia le condizioni, se possibile: ti consigliamo di utilizzare la logica più breve e semplice nelle espressioni delle condizioni IAM, soprattutto se prevedi di avere un numero elevato di condizioni. I criteri di autorizzazione IAM hanno una limitazione delle dimensioni e la semplificazione delle condizioni impedisce di incorrere in queste limitazioni di IAM. Per ulteriori dettagli, consulta la sezione Limitazioni. Ad esempio, puoi omettere il controllo della presenza di una chiave nell'espressione 'user_id' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' e utilizzare invece l'istruzione più breve api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'. Se manca la chiave user_id, l'espressione più lunga restituisce false, mentre l'espressione più breve genera un errore. Poiché gli errori nelle espressioni delle condizioni IAM causano il rifiuto dell'accesso, entrambe le espressioni producono lo stesso risultato.

Ruoli IAM specializzati di Memory Bank

È fondamentale impedire criteri IAM eccessivamente permissivi quando utilizzi le condizioni IAM. La tabella seguente elenca i ruoli specializzati che puoi utilizzare quando concedi ruoli IAM condizionali per le API Memory Bank:

Utilizzo delle condizioni IAM con Memory Bank

Questa sezione illustra i seguenti esempi di utilizzo delle condizioni IAM con Memory Bank:

1. Concede l'accesso in lettura ai ricordi con corrispondenza esatta dell'ambito.

2. Concedi l'accesso in scrittura ai ricordi con ambito contenente una specifica coppia chiave-valore.

3. Concedi l'accesso completo ai ricordi con ambito contenente chiavi specifiche.

4. Concedi l'accesso completo ai ricordi con ambito contenente un prefisso specifico.

5. Concede l'accesso completo ai ricordi con l'ambito della chiave con un insieme di valori consentiti.

Concedere l'accesso in lettura ai ricordi con corrispondenza esatta dell'ambito

La seguente condizione concede all'individuo userA@gmail.com l'accesso in visualizzazione ai ricordi che hanno l'ambito esatto {"userId": "userA"}.

Ciò significa che il membro ha la possibilità di ottenere e recuperare i ricordi, nonché di elencare e ottenere le revisioni di questi ricordi, a condizione che l'ambito sia esattamente {"userId": "userA"}. L'utente non ha accesso ai ricordi con ambito come {'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'}"
  }
}

Concedi l'accesso in scrittura ai ricordi con ambito contenente una coppia chiave-valore specifica

La seguente condizione concede all'individuo developerA@corp.com l'accesso in modifica a tutti i ricordi che contengono la coppia chiave-valore 'userId': 'userA'.

Ciò significa che l'utente ha la possibilità di creare, aggiornare, eliminare e generare ricordi, nonché di creare e ripristinare le revisioni di questi ricordi, con ambiti come {'userId': 'userA'} e {'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'"
  }
}

Concedere l'accesso completo ai ricordi con un ambito contenente chiavi specifiche

La seguente condizione concede all'utente del gruppo group:engineering@corp.com (visualizzatore ed editor) l'accesso ai ricordi che hanno la chiave 'admin_override' o 'public_access_flag'.

Ciò significa che i membri del gruppo hanno accesso completo in lettura e scrittura ai ricordi con ambiti come {'admin_override': 'true'}, {'admin_override': 'true', 'public_access_flag': 'false'} e {'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', {}))"
  }
}

Concedere l'accesso completo ai ricordi con ambito contenente un prefisso specifico

La seguente condizione concede al gruppo group:engineering@corp.com l'accesso (visualizzatore ed editor) ai ricordi che hanno la chiave 'userId' con valore che inizia con 'user'.Puoi utilizzare 'startsWith' per il controllo del prefisso e 'endsWith' per il controllo del suffisso.

Ciò significa che i membri del gruppo hanno accesso completo in lettura e scrittura ai ricordi con ambiti come {'userId': 'userA'} e {'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')"
  }
}

Concede l'accesso completo ai ricordi con l'ambito della chiave con un insieme di valori consentiti

La seguente condizione concede all'utente del gruppo group:engineering@corp.com (visualizzatore ed editor) l'accesso ai ricordi che hanno la chiave 'userId' con valori 'userA' o 'userB'.

Ciò significa che i membri del gruppo hanno accesso completo in lettura e scrittura ai ricordi con ambiti come {'userId': 'userA'} e {'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'] in ['userA', 'userB']"
  }
}

Limitazioni

• Limite di entità: le policy IAM sono limitate a 1500 entità uniche. Questo limite può essere gestito utilizzando i gruppi Google. Scopri di più su Limiti per tutti i principal.

• Supporto API: le condizioni IAM non sono supportate dai metodi che operano su più ambiti, ad esempio ListMemories e PurgeMemories. Per concedere queste autorizzazioni, devi assegnare all'entità un ruolo incondizionato, ad esempio aiplatform.googleapis.com/memoryViewer, aiplatform.googleapis.com/memoryUser o un ruolo incondizionato pertinente della piattaforma agentica Gemini Enterprise.