Controlla l'accesso a Memory Bank con le condizioni IAM

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

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

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

Panoramica

Le condizioni IAM ti consentono di concedere l'accesso alle risorse di memoria e di 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 memorie, come {'user_id': '123'}, che ti consente di organizzare le memorie in base al gruppo a cui appartengono.

Queste policy di Identity and Access Management condizionali vengono create a livello di progetto e si applicano a tutti i ricordi all'interno di un progetto. Puoi applicare le condizioni IAM a tutti i tipi di entità, inclusi gli utenti del 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 alle memorie e alle revisioni in modo che un utente possa accedere solo alle proprie informazioni o in modo che gli sviluppatori possano visualizzare solo determinate risorse della banca della memoria senza concessioni di autorizzazioni speciali.

Prima di iniziare

Per configurare policy IAM condizionali per le memorie e le revisioni delle memorie, segui questi passaggi:

  • 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, prendi in considerazione quanto segue:

    • Se gli sviluppatori devono essere in grado di visualizzare tutti i ricordi.
    • Indica se gli amministratori del progetto devono essere in grado di visualizzare tutti i ricordi.
    • Se determinate identità di agenti possono accedere solo a determinate memorie.
  • Concedi i 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 della banca di memoria della piattaforma dell'agente, 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 della banca di memoria della piattaforma dell'agente. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

    Autorizzazioni obbligatorie

    Per applicare le condizioni IAM alle risorse 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 disporre anche delle autorizzazioni per gestire le policy dell'organizzazione.

Creazione dell'accesso condizionale per i ricordi

L'accesso condizionale alle memorie 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 dell'ambito di una risorsa di memoria. Puoi definire l'ambito quando crei o generi un ricordo.

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

Per concedere un singolo ruolo a un'entità, segui questi passaggi:

Console

  1. Nella console Google Cloud vai alla pagina IAM.

    Vai a IAM

  2. Seleziona il progetto.

  3. 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.

    • 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.

  4. 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.

  5. Aggiungi una condizione al ruolo, utilizzando aiplatform.googleapis.com/memoryScope come attributo API. Consulta gli esempi per alcune possibili istruzioni di condizione.

  6. Fai clic su Salva. All'entità viene concesso il ruolo sulla risorsa.

gcloud

  1. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud , viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Il comando add-iam-policy-binding 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 PRINCIPAL può avere, consulta Identificatori delle entità.

      Per il tipo di entità user, il nome di dominio nell'identificatore deve essere un dominio Google Workspace o un dominio 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 dell'API. Consulta gli esempi riportati di seguito per alcune possibili istruzioni di condizione.

    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 la policy IAM aggiornata.

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 le policy 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 MEMBER può avere, consulta Identificatori delle entità.
  • CONDITION: l'istruzione della condizione IAM che utilizza aiplatform.googleapis.com/memoryScope come attributo dell'API. Consulta gli esempi per alcune possibili istruzioni di condizione.

Best practice per le autorizzazioni a livello di ambito

Quando crei le condizioni per Memory Bank, segui queste best practice:

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

  2. Utilizza condizioni positive: per una maggiore precisione, ti consigliamo di utilizzare condizioni positive (ad esempio controlli per l'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 inavvertitamente corrispondere a un'ampia gamma di risorse, il che può essere eccessivamente permissivo e consentire la concessione di autorizzazioni impreviste.

  3. Abbrevia le condizioni, se possibile: ti consigliamo di utilizzare la logica più breve e semplice possibile nelle espressioni delle condizioni IAM, soprattutto se prevedi di avere un numero elevato di condizioni. Le policy di autorizzazione IAM hanno un limite di 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' e utilizzare invece l'istruzione più breve api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'. Se la chiave user_id non è presente, 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 per la banca di memoria

È fondamentale evitare 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:

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 alle memorie e l'accesso in rollback alle revisioni della memoria.
  • 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:

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

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

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

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

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

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

La seguente condizione concede alla persona 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, purché l'ambito sia esattamente {"userId": "userA"}. L'utente non ha accesso ai ricordi con un 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 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 memorie, nonché di creare ed eseguire il rollback delle revisioni di queste memorie, 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'"
  }
}

Concedi l'accesso completo alle memorie con un ambito contenente chiavi specifiche

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

Ciò significa che i membri del gruppo hanno accesso completo in lettura e scrittura alle memorie 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', {}))"
  }
}

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

La seguente condizione concede all'utente del gruppo group:engineering@corp.com (visualizzatore ed editor) l'accesso ai ricordi con 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')"
  }
}

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

La seguente condizione concede al gruppo group:engineering@corp.com l'accesso utente (visualizzatore ed editor) alle memorie con 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'}, {'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 Google Gruppi. Per saperne di più, consulta Limiti per tutte le entità.

  • Supporto delle API: le condizioni IAM non sono supportate dai metodi che operano su più ambiti, come 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 della piattaforma agentica Gemini Enterprise incondizionato pertinente.