Contrôler l'accès aux sessions avec des conditions IAM

Par défaut, les autorisations Identity and Access Management des sessions sont définies au niveau du projet. Ce document explique comment utiliser les conditions IAM pour contrôler plus précisément l'accès aux ressources de sessions Vertex AI Agent Engine.

Présentation

Les conditions IAM vous permettent de n'accorder l'accès aux ressources d'événements de session et de session que si les conditions spécifiées sont remplies. Vous pouvez contrôler l'accès aux sessions en fonction de la chaîne userId dans la ressource Session à l'aide de l'attribut d'API aiplatform.googleapis.com/sessionUserId avec une expression écrite en langage Common Expression Language. L'ID utilisateur est une chaîne arbitraire fournie lors de la création de sessions, comme userId = "userA".

Ces stratégies Identity and Access Management conditionnelles sont créées au niveau du projet et s'appliquent à toutes les sessions et à tous les événements de session d'un projet. Vous pouvez appliquer des conditions IAM à tous les types de comptes principaux, y compris les utilisateurs de votre projet et les comptes de service.

Les conditions IAM sont utiles pour accorder des autorisations Identity and Access Management (IAM) à de nombreuses ressources de session associées en même temps, y compris à celles qui n'existent pas encore. Vous pouvez limiter l'accès à vos sessions et événements afin qu'un utilisateur ne puisse accéder qu'à ses propres informations, ou afin que les développeurs ne puissent consulter que certaines ressources de session sans autorisation spéciale.

Avant de commencer

Pour configurer des règles Identity and Access Management conditionnelles pour les sessions et les événements de session, procédez comme suit :

Consultez les conditions IAM : familiarisez-vous avec la présentation des conditions IAM.
Déterminez les rôles nécessaires : identifiez les rôles IAM de session spécialisés qui conviennent à votre cas d'utilisation pour respecter le principe du moindre privilège.
Identifier les comptes principaux concernés : identifiez les membres de votre organisation qui doivent recevoir quelles autorisations. Par exemple, prenons le cas suivant :
- Les utilisateurs doivent-ils pouvoir voir les sessions d'autres utilisateurs ?
- Les développeurs doivent-ils pouvoir voir toutes les sessions ?
- Les administrateurs de projet doivent-ils pouvoir voir toutes les sessions ?
- Certaines identités d'agent doivent-elles pouvoir accéder à certaines sessions ?
Attribuez des rôles IAM : assurez-vous de disposer des rôles requis contenant les autorisations nécessaires pour effectuer les tâches décrites dans ce document.
Pour obtenir les autorisations nécessaires pour appliquer des conditions IAM aux ressources de session Vertex AI Agent Engine, demandez à votre administrateur de vous accorder les rôles IAM suivants :
- Pour les projets : Administrateur de projet IAM (`roles/resourcemanager.projectIamAdmin`)
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour appliquer des conditions IAM aux ressources de session Vertex AI Agent Engine. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :
Autorisations requises

Les autorisations suivantes sont requises pour appliquer des conditions IAM aux ressources de session Vertex AI Agent Engine :
- Définissez un accès IAM conditionnel au niveau du projet : `resourcemanager.projects.setIamPolicy`
Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.
Si vous envisagez d'utiliser des conditions IAM au sein de votre organisation, vous devez également disposer d'autorisations permettant de gérer les règles d'administration.

Créer un accès conditionnel pour les sessions

Accordez un accès conditionnel aux sessions en ajoutant une condition à une liaison de stratégie Identity and Access Management au niveau du projet. La condition utilise la fonction api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") pour inspecter l'ID utilisateur de la ressource de session. Vous définissez un ID utilisateur lorsque vous créez une session.

Pour obtenir un guide détaillé sur la création de stratégies IAM avec des conditions, consultez Conditions dans les stratégies d'autorisation.

Pour attribuer un seul rôle à un compte principal, procédez comme suit :

Console

Dans la console Google Cloud , accédez à la page IAM.

Accéder à IAM
Sélectionnez votre projet.
Sélectionnez un compte principal auquel attribuer un rôle :
- Pour attribuer un rôle à un compte principal qui dispose déjà d'autres rôles sur la ressource, recherchez la ligne contenant le compte principal, puis cliquez sur Modifier le compte principal sur cette ligne, puis sur Ajouter un autre rôle.
  
  Pour attribuer un rôle à un agent de service, cochez la case Inclure les attributions de rôles fournies parGoogle pour afficher son adresse e-mail.
  
  Remarque : Vous ne pouvez pas modifier les rôles hérités lorsque vous gérez l'accès à une ressource. Pour modifier les rôles hérités, accédez à la ressource où le rôle a été accordé.
- Pour attribuer un rôle à un compte principal qui ne dispose d'aucun rôle sur la ressource, cliquez sur Accorder l'accès, puis saisissez un identifiant de compte principal (par exemple, my-user@example.com ou //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com).
Sélectionnez un rôle à attribuer dans la liste déroulante. Pour respecter les bonnes pratiques de sécurité, choisissez un rôle qui n'inclut que les autorisations dont votre compte principal a besoin. Vous pouvez choisir l'un des rôles IAM de session spécialisés.
Ajoutez une condition au rôle en utilisant aiplatform.googleapis.com/sessionUserId comme attribut d'API. Consultez les exemples ci-dessous pour découvrir des exemples d'énoncés de conditions possibles.
Cliquez sur Enregistrer. Le rôle est attribué au compte principal sur la ressource.

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.
La commande add-iam-policy-binding vous permet d'attribuer rapidement un rôle à un compte principal.

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud . Les ID de projets sont alphanumériques, par exemple my-project.
- PRINCIPAL : identifiant du compte principal ou membre, se présentant généralement sous la forme suivante : PRINCIPAL_TYPE:ID. Par exemple, user:my-user@example.com ou principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Pour obtenir la liste complète des valeurs possibles pour PRINCIPAL, consultez Identifiants de comptes principaux.
  
  Pour le type de compte principal user, le nom de domaine indiqué dans l'identifiant doit être un domaine Google Workspace ou Cloud Identity. Pour savoir comment configurer un domaine Cloud Identity, consultez la présentation de Cloud Identity.
- ROLE_NAME : nom du rôle que vous souhaitez révoquer. Utilisez l'un des formats suivants :
  - Rôles prédéfinis : roles/aiplatform.IDENTIFIER
  - Rôles personnalisés au niveau du projet : projects/PROJECT_ID/roles/IDENTIFIER
  Sélectionnez un rôle à attribuer dans la liste déroulante. Pour respecter les bonnes pratiques de sécurité, choisissez un rôle qui n'inclut que les autorisations dont votre compte principal a besoin. Vous pouvez choisir l'un des rôles IAM de session spécialisés.
- CONDITION : ajoutez une condition au rôle en utilisant aiplatform.googleapis.com/sessionUserId comme attribut d'API. Consultez les exemples ci-dessous pour découvrir des exemples d'énoncés de conditions possibles.
Exécutez la commande suivante :
Linux, macOS ou 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 réponse contient la stratégie IAM mise à jour.

Terraform

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de base. Pour en savoir plus, lisez la documentation de référence du fournisseur Terraform.

Si vous utilisez Terraform pour définir vos stratégies IAM, vous pouvez inclure une condition dans la ressource google_project_iam_member afin de limiter l'accès d'un membre aux sessions.

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

Remplacez les variables suivantes :

PROJECT_ID : ID de votre projet Google Cloud . Les ID de projets sont alphanumériques, par exemple my-project.
ROLE : rôle IAM à accorder, par exemple roles/aiplatform.sessionEditor.
MEMBER : compte principal auquel attribuer le rôle, par exemple user:developerA@corp.com. Pour obtenir la liste complète des valeurs possibles pour MEMBER, consultez Identifiants de comptes principaux.
CONDITION : instruction de condition IAM utilisant aiplatform.googleapis.com/sessionUserId comme attribut d'API. Consultez les exemples ci-dessous pour découvrir des exemples d'énoncés de conditions possibles.

Bonnes pratiques pour les autorisations au niveau de l'ID utilisateur

Lorsque vous créez des conditions pour les sessions, suivez les bonnes pratiques suivantes :

Utilisez des rôles IAM de session spécialisés : les conditions IAM de session ne doivent être utilisées que pour les rôles qui s'appliquent aux sessions et aux événements de session. Vous pouvez utiliser des rôles spécialisés tels que aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor et aiplatform.googleapis.com/sessionUser pour éviter les accès trop permissifs. Pour en savoir plus, consultez la section Rôles IAM de session spécialisés.
Utilisez des conditions positives : nous vous recommandons d'utiliser des conditions positives (telles que des vérifications d'égalité ou la présence de préfixes) sur aiplatform.googleapis.com/sessionUserId pour une plus grande précision. Étant donné que les types et services non compatibles sont représentés par un ID utilisateur vide, les conditions négatives (telles que les vérifications d'inégalité) peuvent correspondre par inadvertance à un large éventail de ressources, ce qui peut être trop permissif et permettre l'octroi d'autorisations inattendues.
Raccourcissez les conditions si possible : nous vous recommandons d'utiliser la logique la plus courte et la plus simple possible dans vos expressions de conditions IAM, en particulier si vous prévoyez d'avoir un grand nombre de conditions. Les stratégies d'autorisation IAM sont limitées en taille. Simplifier les conditions vous permettra d'éviter les limites IAM. Pour en savoir plus, consultez Limites. Par exemple, vous pouvez simplifier la vérification de deux User-ID différents en combinant l'instruction composée api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB', car elle donne le même résultat que l'instruction plus courte api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Rôles IAM de session spécialisés

Il est essentiel d'éviter les stratégies IAM trop permissives lorsque vous utilisez des conditions IAM. Le tableau suivant liste les rôles spécialisés que vous pouvez utiliser lorsque vous accordez des rôles IAM conditionnels pour les API de session :

Nom du rôle	Description	Autorisations associées
`roles/aiplatform.sessionViewer`	Accorde un accès en lecture seule aux sessions et aux événements de fiche.	`aiplatform.googleapis.com/sessions.get` `aiplatform.googleapis.com/sessions.list` `aiplatform.googleapis.com/sessionEvents.list`
`roles/aiplatform.sessionEditor`	Accorde un accès en écriture aux sessions et aux événements ajoutés.	`aiplatform.googleapis.com/sessions.create` `aiplatform.googleapis.com/sessions.update` `aiplatform.googleapis.com/sessions.delete` `aiplatform.googleapis.com/sessionEvents.append`
`roles/aiplatform.sessionUser`	Accorde un accès complet aux sessions et aux événements, y compris toutes les autorisations de lecteur et d'éditeur.	Inclut toutes les autorisations de `sessionEditor` et de `sessionViewer`.

Utiliser des conditions IAM avec les sessions

Cette section présente les exemples suivants d'utilisation des conditions IAM avec les sessions :

Accorder un accès en lecture aux sessions dont l'User-ID correspond exactement.
Accorder un accès en écriture aux sessions contenant un préfixe spécifique dans l'ID utilisateur
Accorder un accès complet aux sessions contenant l'un des deux ID utilisateur

Accorder un accès en lecture aux sessions avec une correspondance exacte de l'ID utilisateur

La condition suivante accorde à l'utilisateur userA@gmail.com un accès en lecture uniquement aux sessions dont l'ID utilisateur est exactement userA.

Cela signifie que la personne peut obtenir des sessions et lister les événements de session, à condition que l'ID utilisateur soit exactement userA. L'utilisateur n'a pas accès aux sessions avec un ID utilisateur tel que userB.

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

Accorder un accès en écriture aux sessions contenant un préfixe spécifique dans l'ID utilisateur

La condition suivante accorde à l'utilisateur developerA@corp.com un accès en modification à toutes les sessions contenant un ID utilisateur commençant par user. Vous pouvez utiliser startsWith pour vérifier les préfixes et endsWith pour vérifier les suffixes.

Cela signifie que le développeur peut créer, modifier et supprimer des sessions, ainsi qu'ajouter des événements, avec des ID utilisateur tels que userA ou user1234.

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

Accorder un accès complet aux sessions contenant l'un des deux ID utilisateur

La condition suivante accorde au groupe d'utilisateurs group:engineering@corp.com (lecteurs et éditeurs) l'accès aux sessions qui n'ont que les ID utilisateur userA ou 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']"
  }
}

Limites

Limite d'entités principales : les stratégies IAM sont limitées à 1 500 entités principales uniques. Vous pouvez gérer cette limite à l'aide des groupes Google. Pour en savoir plus, consultez Limites sur tous les comptes principaux.
Compatibilité avec l'API ListSessions : l'API ListSessions n'est pas compatible avec les conditions IAM. Pour accorder des autorisations ListSessions, vous devez attribuer au compte principal un rôle inconditionnel, tel que aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser ou un rôle Vertex AI inconditionnel pertinent.