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

Par défaut, les autorisations Identity and Access Management (IAM) 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 d'événements de session et 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, 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 afficher que certaines ressources de session sans autorisation spéciale.

Avant de commencer

Pour configurer des règles IAM (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 membres de votre organisation qui doivent recevoir quelles autorisations. Par exemple, prenons le cas suivant :
  • 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 Conditions dans les stratégies d'autorisation.

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

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

Bonnes pratiques concernant 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 les accès trop permissifs. Pour en savoir plus, consultez la section Rôles IAM pour les sessions spécialisées.

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 d'autorisations inattendu.

3. Raccourcissez les conditions si possible : nous vous recommandons d'utiliser la logique la plus courte et la plus simple 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 sont soumises à une limite de 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 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'é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 :

Utiliser des conditions IAM avec les sessions

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

1. Accorder un accès en lecture aux sessions dont l'ID utilisateur correspond exactement.

2. Accorder l'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 userA@gmail.com qu'un accès en lecture 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 l'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 dont l'ID utilisateur commence 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, mettre à jour 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 group:engineering@corp.com (lecteur et éditeur) l'accès aux sessions qui ne comportent 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

1. 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 de groupes Google. Pour en savoir plus, consultez Limites sur tous les comptes principaux.

2. Compatibilité de l'API ListSessions : l'API ListSessions n'est pas compatible avec les conditions IAM. Pour accorder des autorisations ListSessions, vous devez attribuer au principal un rôle inconditionnel, tel que aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser ou un rôle Gemini Enterprise Agent Platform inconditionnel pertinent.