Controllare 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 di 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 delle 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 sessioni e agli eventi in modo che un utente possa accedere solo alle proprie informazioni o che gli sviluppatori possano visualizzare solo determinate risorse Session senza concessioni di autorizzazioni speciali.

Prima di iniziare

Per configurare le policy IAM (Identity and Access Management) condizionali per le sessioni e gli eventi di sessione:

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à di agenti 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: 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 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 disporre anche delle autorizzazioni per gestire i criteri 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 esaminare 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à:

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 di sessione specializzati.
Aggiungi una condizione al ruolo utilizzando aiplatform.googleapis.com/sessionUserId 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 di sessione specializzati.
- CONDITION: aggiungi una condizione al ruolo utilizzando aiplatform.googleapis.com/sessionUserId 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 alle sessioni.

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

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.sessionEditor.
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/sessionUserId come attributo API. Vedi gli esempi riportati di seguito per alcune possibili istruzioni condizionali.

Best practice per le autorizzazioni a livello di ID utente

Quando crei condizioni per le sessioni, utilizza le seguenti best practice:

Utilizza ruoli IAM per sessioni specializzati: le condizioni IAM per sessioni devono essere utilizzate solo per i ruoli che si applicano a sessioni ed eventi di sessione. Puoi utilizzare ruoli specializzati come aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor e aiplatform.googleapis.com/sessionUser per impedire l'accesso eccessivamente permissivo. Per ulteriori dettagli, consulta la sezione Ruoli IAM per sessioni specializzate.
Utilizza condizioni positive: per una maggiore precisione, ti consigliamo di utilizzare condizioni positive (ad esempio controlli di uguaglianza o presenza di prefissi) su aiplatform.googleapis.com/sessionUserId. 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.
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 in limitazioni IAM. Per ulteriori dettagli, consulta la sezione Limitazioni. Ad esempio, puoi semplificare il controllo di due ID utente diversi combinando l'istruzione composta: api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB', che 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 si utilizzano le condizioni IAM. La tabella seguente elenca i ruoli specializzati che puoi utilizzare quando concedi ruoli IAM condizionali per le API di sessione:

Nome ruolo	Descrizione	Autorizzazioni incluse
`roles/aiplatform.sessionViewer`	Concede l'accesso di sola lettura a sessioni ed eventi di schede.	`aiplatform.googleapis.com/sessions.get` `aiplatform.googleapis.com/sessions.list` `aiplatform.googleapis.com/sessionEvents.list`
`roles/aiplatform.sessionEditor`	Concede l'accesso in scrittura alle sessioni e agli eventi di accodamento.	`aiplatform.googleapis.com/sessions.create` `aiplatform.googleapis.com/sessions.update` `aiplatform.googleapis.com/sessions.delete` `aiplatform.googleapis.com/sessionEvents.append`
`roles/aiplatform.sessionUser`	Concede l'accesso completo a sessioni ed eventi, incluse tutte le autorizzazioni di visualizzatore ed editor.	Include tutte le autorizzazioni di `sessionEditor` e `sessionViewer`.

Utilizzo delle condizioni IAM con le sessioni

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

Concedi l'accesso in lettura alle sessioni con corrispondenza esatta dell'ID utente.
Concedere l'accesso in scrittura alle sessioni contenenti un prefisso specifico nell'ID utente.
Concedere l'accesso completo alle sessioni contenenti uno dei due User-ID.

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

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

Ciò significa che la persona ha la possibilità di ottenere sessioni ed elencare gli eventi della 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 qualsiasi sessione che contenga 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 (visualizzatore ed editor) del gruppo group:engineering@corp.com 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

Limite di entità: i criteri IAM sono limitati a 1500 entità uniche. Questo limite può essere gestito utilizzando Google Gruppi. Scopri di più in Limiti per tutte le entità.
Supporto dell'API ListSessions: l'API ListSessions non supporta le condizioni IAM. Per concedere le autorizzazioni ListSessions, devi concedere all'entità un ruolo incondizionato, ad esempio aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser o un ruolo Vertex AI incondizionato pertinente.