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 d'accorder l'accès aux ressources de session et d'événement de session uniquement 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 Common Expression Language. L'ID utilisateur est une chaîne arbitraire fournie lors de la création de sessions, par exemple 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 aux utilisateurs de votre projet et aux 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 restreindre l'accès à vos sessions et événements afin qu'un utilisateur ne puisse accéder qu'à ses propres informations ou que les développeurs ne puissent afficher que certaines ressources de session sans autorisation spéciale.

Avant de commencer

Pour configurer des stratégies 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 garantir le principe du moindre privilège.
• Identifiez les comptes principaux concernés : identifiez les personnes de votre organisation qui doivent recevoir quelles autorisations. Par exemple, réfléchissez aux points suivants :
  • Les utilisateurs doivent-ils pouvoir voir les sessions d'un autre utilisateur ?
  • 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 la section Conditions dans les stratégies d'autorisation.

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

Console

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

   Accéder à IAM

2. Sélectionnez votre projet.

3. 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 cliquez sur Ajouter un autre rôle.

     Pour attribuer un rôle à un agent de service, cochez la case Inclure Google-fournies 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, [e-mail] ou //iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail].

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

5. Ajoutez une condition au rôle en utilisant aiplatform.googleapis.com/sessionUserId comme attribut d'API. Consultez les exemples ci-dessous pour obtenir des exemples d'instructions de condition possibles.

6. Cliquez sur Enregistrer. Le rôle est attribué au compte principal sur la ressource.

gcloud

1. Dans la Google Cloud console, activez Cloud Shell.

   Activer Cloud Shell

   En bas de la Google Cloud console, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

2. 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 Google Cloud projet. 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:[e-mail] ou principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail]. Pour obtenir la liste complète des valeurs possibles pour PRINCIPAL, consultez Identifiants du compte principal.

     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 obtenir des exemples d'instructions de condition 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, consultez la Terraform documentation de référence du fournisseur.

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 Google Cloud projet. Les ID de projets sont alphanumériques, par exemple my-project.

• ROLE : rôle IAM à attribuer, par exemple roles/aiplatform.sessionEditor.

• MEMBER : compte principal auquel attribuer le rôle, par exemple user:[e-mail]. Pour obtenir la liste complète des valeurs possibles pour MEMBER, consultez Identifiants du compte principal.

• CONDITION : instruction de condition IAM utilisant aiplatform.googleapis.com/sessionUserId comme attribut d'API. Consultez les exemples ci-dessous pour obtenir des exemples d'instructions de condition 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 :

1. 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 un accès trop permissif. Pour en savoir plus, consultez la section Rôles IAM de session spécialisés.
2. 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 inattendu d'autorisations.
3. Raccourcissez les conditions si possible : nous vous recommandons d'utiliser la logique la plus courte et la plus simple possible dans vos expressions de condition IAM, en particulier si vous prévoyez d'avoir un grand nombre de conditions. Les stratégies d'autorisation IAM ont une limite de taille, et la simplification des conditions vous évitera de rencontrer des limites IAM. Pour en savoir plus, consultez Limites. Par exemple, vous pouvez simplifier la vérification de deux ID utilisateur 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'empêcher les stratégies IAM trop permissives lorsque vous utilisez des conditions IAM. Le tableau suivant répertorie 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 liste.	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 d'ajout.	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 des sessions

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

1. Accorder un accès en lecture aux sessions avec une correspondance exacte de l'ID utilisateur.
2. Accorder un accès en écriture aux sessions contenant un préfixe spécifique dans l'ID utilisateur.
3. 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 n'accorde à l'utilisateur [e-mail] qu'un accès en lecture aux sessions dont l'ID utilisateur est exactement userA.

Cela signifie que l'utilisateur 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 dont l'ID utilisateur est userB, par exemple.

{
  "members": ["user:[e-mail]"],
  "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 [e-mail] un accès en modification à toutes les sessions dont l'ID utilisateur commence par user. Vous pouvez utiliser startsWith pour vérifier le préfixe et endsWith pour vérifier le suffixe.

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:[e-mail]"],
  "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 group:[e-mail] un accès utilisateur (lecteur et éditeur) aux sessions dont les ID utilisateur sont uniquement userA ou user123.

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

Limites

1. Limite de comptes principaux : les stratégies IAM sont limitées à 1 500 comptes principaux uniques. Vous pouvez gérer cette limite à l'aide des groupes Google. Pour en savoir plus, consultez Limites sur tous les comptes principaux.
2. 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.