Controlla l'accesso alle sessioni con le condizioni IAM

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

Panoramica

Le condizioni IAM consentono di concedere l'accesso alle risorse di sessione e agli eventi di sessione solo se sono soddisfatte le condizioni specificate. Puoi controllare l'accesso alle sessioni in base alla stringa userId all'interno della risorsa Sessione utilizzando l'attributo API aiplatform.googleapis.com/sessionUserId con un'espressione scritta in Common Expression Language. L'ID utente è una stringa arbitraria fornita durante la creazione di sessioni, ad esempio userId = "userA".

Questi criteri Identity and Access Management condizionali vengono creati a livello di progetto e si applicano a tutte le sessioni e a tutti gli eventi di sessione 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 di sessione correlate contemporaneamente, incluse quelle che non esistono ancora. Puoi limitare l'accesso alle tue sessioni ed eventi in modo che un utente possa accedere solo alle proprie informazioni o in modo che gli sviluppatori possano visualizzare solo determinate risorse Session senza concessioni di autorizzazioni speciali.

Prima di iniziare

Per configurare le policy Identity and Access Management condizionali per le sessioni e gli eventi di sessione, procedi nel seguente modo:

• Esamina le condizioni IAM: acquisisci familiarità con la panoramica delle condizioni IAM.
• Determina i ruoli necessari: identifica quali ruoli IAM di sessione specializzati 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:
  • Gli utenti devono essere in grado di vedere le sessioni di un altro utente?
  • Gli sviluppatori devono essere in grado di vedere tutte le sessioni?
  • Gli amministratori del progetto devono essere in grado di vedere tutte le sessioni?
  • Determinate identità dell'agente devono poter accedere a determinate sessioni?
• 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 di sessione di Vertex AI Agent Engine, 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 di sessione 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 sessione 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 anche disporre delle autorizzazioni per gestire le policy dell'organizzazione.

Creazione dell'accesso condizionale per le sessioni

Concedi l'accesso condizionale alle sessioni aggiungendo una condizione a un'associazione di policy Identity and Access Management a livello di progetto. La condizione utilizza la funzione api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") per ispezionare l'ID utente della risorsa sessione. Definisci un ID utente quando crei una sessione.

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       = "Session Access Condition"
    description = "IAM condition for Session"
    expression  = "CONDITION"
  }
}

Best practice per le autorizzazioni a livello di ID utente

Quando crei condizioni per le sessioni, segui queste best practice:

1. Utilizza ruoli IAM di sessione specializzati: le condizioni IAM di sessione devono essere utilizzate solo per i ruoli che si applicano alle sessioni e agli eventi di sessione. Puoi utilizzare ruoli specializzati come aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor e aiplatform.googleapis.com/sessionUser per impedire un accesso eccessivamente permissivo. Per ulteriori dettagli, consulta la sezione Ruoli IAM per sessioni specializzate.

2. Utilizza condizioni positive: ti consigliamo di utilizzare condizioni positive (ad esempio controlli di uguaglianza o presenza di prefissi) su aiplatform.googleapis.com/sessionUserId per una maggiore accuratezza. Poiché i tipi e i servizi non supportati sono rappresentati da un ID utente 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 eviterà di incorrere nelle limitazioni di IAM. Per ulteriori dettagli, consulta la sezione Limitazioni. Ad esempio, puoi semplificare il controllo di due diversi ID utente combinando l'istruzione composta: api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB' in quanto restituisce lo stesso risultato dell'istruzione più breve api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Ruoli IAM di sessione specializzati

È 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 di sessione:

Utilizzo delle condizioni IAM con le sessioni

Questa sezione illustra i seguenti esempi di utilizzo delle condizioni IAM con le sessioni:

1. Concedi l'accesso in lettura alle sessioni con corrispondenza esatta dell'ID utente.

2. Concedere l'accesso in scrittura alle sessioni contenenti un prefisso specifico nell'ID utente.

3. Concedi l'accesso completo alle sessioni contenenti uno dei due ID utente.

Concedere l'accesso in lettura alle sessioni con corrispondenza esatta dell'ID utente

La seguente condizione concede all'individuo userA@gmail.com l'accesso in visualizzazione alle sessioni che hanno l'ID utente esatto userA.

Ciò significa che l'individuo ha la possibilità di ottenere sessioni ed elencare gli eventi di sessione, a condizione che l'ID utente sia esattamente userA. L'utente non ha accesso alle sessioni con ID utente come userB.

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

Concedere l'accesso in scrittura alle sessioni contenenti un prefisso specifico nell'ID utente

La seguente condizione concede all'individuo developerA@corp.com l'accesso in modifica a tutte le sessioni che contengono l'ID utente che inizia con user. Puoi utilizzare startsWith per il controllo del prefisso e endsWith per il controllo del suffisso.

Ciò significa che lo sviluppatore ha la possibilità di creare, aggiornare ed eliminare sessioni, nonché di aggiungere eventi, con ID utente come userA o user1234.

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.sessionEditor",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '').startsWith('user')"
  }
}

Concedere l'accesso completo alle sessioni contenenti uno dei due ID utente

La seguente condizione concede all'utente del gruppo group:engineering@corp.com (visualizzatore ed editor) l'accesso alle sessioni che hanno solo ID utente userA o user123.

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.sessionUser",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['userA', 'user123']"
  }
}

Limitazioni

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

2. Supporto dell'API ListSessions: l'API ListSessions non supporta le condizioni IAM. Per concedere le autorizzazioni ListSessions, devi concedere al principal un ruolo incondizionato, ad esempio aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser o un ruolo Gemini Enterprise Agent Platform incondizionato pertinente.