Controllare l'accesso a Memory Bank con le condizioni IAM

Per impostazione predefinita, le autorizzazioni Identity and Access Management per la memoria sono a livello di progetto. Questo documento descrive come utilizzare le condizioni IAM per controllare l'accesso più granulare alle risorse di Memory Bank di Vertex AI Agent Engine.

Panoramica

Le condizioni IAM ti 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 memoria 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, ad esempio {'user_id': '123'}, che 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 le 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 quali ruoli IAM specializzati di Memory Bank sono 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:
- Indica 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 Vertex AI Agent Engine, chiedi all'amministratore di concederti i seguenti ruoli IAM:
- Per i progetti: Project IAM Admin (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 Vertex AI Agent Engine. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie

Per applicare le condizioni IAM alle risorse di Memory Bank di Vertex AI Agent Engine 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 disporre anche 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 esaminare la mappa dell'ambito 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à:

Console

Nella console Google Cloud , vai alla pagina IAM.

Vai a IAM
Seleziona il progetto.
Seleziona un'entità a cui assegnare un ruolo:
- Per concedere un ruolo a un'entità che ha già altri ruoli nella risorsa, individua una riga contenente l'entità, fai clic su Modifica entità in quella riga e fai clic su Aggiungi un altro ruolo.
  
  Per concedere un ruolo a un agente di servizio, seleziona la casella di controllo Includi concessioni di ruoli fornite da Google per visualizzarne l'indirizzo email.
  
  Nota: non puoi modificare i ruoli ereditati quando gestisci l'accesso a una risorsa. Per modificare i ruoli ereditati, vai alla risorsa in cui è stato concesso il ruolo.
- Per concedere un ruolo a un'entità che non ha ruoli esistenti per la risorsa, fai clic su Concedi l'accesso, quindi inserisci un identificatore dell'entità, ad esempio my-user@example.com o //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.
Seleziona un ruolo da concedere dall'elenco a discesa. Per le best practice di sicurezza, scegli un ruolo che includa solo le autorizzazioni necessarie all'entità. Puoi scegliere uno dei ruoli IAM specializzati di Memory Bank.
Aggiungi una condizione al ruolo utilizzando aiplatform.googleapis.com/memoryScope come attributo API. Vedi gli esempi riportati di seguito per alcune possibili istruzioni condizionali.
Fai clic su Salva. All'entità viene concesso il ruolo sulla risorsa.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Il comando add-iam-policy-binding ti consente di concedere rapidamente un ruolo a un'entità.

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:
- PROJECT_ID: l'ID progetto Google Cloud . Gli ID progetto sono alfanumerici, ad esempio my-project.
- PRINCIPAL: un identificatore per l'entità o il membro, che di solito ha il seguente formato: PRINCIPAL_TYPE:ID. Ad esempio, user:my-user@example.com o principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Per un elenco completo dei valori che può assumere PRINCIPAL, consulta Identificatori delle entità.
  
  Per il tipo di entità user, il nome di dominio nell'identificatore deve essere un dominio Google Workspace o Cloud Identity. Per scoprire come configurare un dominio Cloud Identity, consulta la panoramica di Cloud Identity.
- ROLE_NAME: il nome del ruolo che vuoi revocare. Utilizza uno dei seguenti formati:
  - Ruoli predefiniti: roles/aiplatform.IDENTIFIER
  - Ruoli personalizzati a livello di progetto: projects/PROJECT_ID/roles/IDENTIFIER
  Seleziona un ruolo da concedere dall'elenco a discesa. Per le best practice di sicurezza, scegli un ruolo che includa solo le autorizzazioni necessarie all'entità. Puoi scegliere uno dei ruoli IAM specializzati di Memory Bank.
- CONDITION: aggiungi una condizione al ruolo utilizzando aiplatform.googleapis.com/memoryScope come attributo API. Vedi gli esempi riportati di seguito per alcune possibili istruzioni condizionali.
Esegui questo comando:
Linux, macOS o Cloud Shell
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION
```
Windows (PowerShell)
```
gcloud projects add-iam-policy-binding PROJECT_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION
```
Windows (cmd.exe)
```
gcloud projects add-iam-policy-binding PROJECT_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION
```
La risposta contiene il criterio IAM aggiornato.

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per saperne di più, consulta la documentazione di riferimento del fornitore Terraform.

Se utilizzi Terraform per impostare i criteri IAM, puoi includere una condizione nella risorsa google_project_iam_member per limitare l'accesso di un membro ai ricordi.

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"
  }
}

Sostituisci le seguenti variabili:

PROJECT_ID: l'ID progetto Google Cloud . Gli ID progetto sono alfanumerici, ad esempio my-project.
ROLE: il ruolo IAM da concedere, ad esempio roles/aiplatform.memoryEditor.
MEMBER: l'entità a cui concedere il ruolo, ad esempio user:developerA@corp.com. Per un elenco completo dei valori che può assumere MEMBER, consulta Identificatori delle entità.
CONDITION: la tua istruzione di condizione IAM che utilizza aiplatform.googleapis.com/memoryScope come attributo API. Vedi gli esempi riportati di seguito per alcune possibili istruzioni condizionali.

Best practice per le autorizzazioni a livello di ambito

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

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 specializzati di Memory Bank.
Utilizza condizioni positive: per una maggiore precisione, ti consigliamo di utilizzare condizioni positive (ad esempio controlli di uguaglianza o la presenza di coppie chiave-valore) su aiplatform.googleapis.com/memoryScope. 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.
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 evita di incorrere in queste limitazioni 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', in quanto restituisce lo stesso risultato dell'istruzione più breve api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'.

Ruoli IAM specializzati per Memory Bank

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

Nome ruolo	Descrizione	Autorizzazioni incluse
`roles/aiplatform.memoryViewer`	Concede l'accesso di sola lettura ai ricordi e alle revisioni dei ricordi.	`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`
`roles/aiplatform.memoryEditor`	Concede l'accesso in scrittura e generazione ai ricordi e l'accesso al rollback alle revisioni dei ricordi.	`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`
`roles/aiplatform.memoryUser`	Concede l'accesso completo a ricordi e revisioni, incluse tutte le autorizzazioni di visualizzatore ed editor.	Include tutte le autorizzazioni di `memoryEditor` e `memoryViewer`.

Utilizzo delle condizioni IAM con Memory Bank

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

Concede l'accesso in lettura ai ricordi con corrispondenza esatta dell'ambito.
Concedi l'accesso in scrittura ai ricordi con un ambito contenente una coppia chiave-valore specifica.
Concedere l'accesso completo ai ricordi con un ambito contenente chiavi specifiche.
Concedere l'accesso completo ai ricordi con ambito contenente un prefisso specifico.
Concedi 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 solo 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 ambiti 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'}"
  }
}

Concedere l'accesso in scrittura ai ricordi con un 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 (visualizzatore ed editor) del gruppo group:engineering@corp.com 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 all'utente del gruppo group:engineering@corp.com (visualizzatore ed editor) l'accesso 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'}, {'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')"
  }
}

Concedere 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'.