Controla el acceso a las sesiones con condiciones de IAM

De forma predeterminada, los permisos de Identity and Access Management de las sesiones se encuentran a nivel del proyecto. En este documento, se describe cómo usar las condiciones de IAM para controlar el acceso más detallado a los recursos de sesiones de Vertex AI Agent Engine.

Descripción general

Las condiciones de IAM te permiten otorgar acceso a los recursos de sesión y eventos de sesión solo si se cumplen las condiciones especificadas. Puedes controlar el acceso a las sesiones según la cadena userId dentro del recurso Session con el atributo de la API aiplatform.googleapis.com/sessionUserId y una expresión escrita en Common Expression Language. El ID de usuario es una cadena arbitraria que se proporciona cuando se crean sesiones, como userId = "userA".

Estas políticas condicionales de Identity and Access Management se crean a nivel del proyecto y se aplican a todas las sesiones y eventos de sesión dentro de un proyecto. Puedes aplicar condiciones de IAM a todo tipo de principales, incluidos los usuarios de tu proyecto y las cuentas de servicio.

Las condiciones de IAM son útiles para otorgar permisos de Identity and Access Management (IAM) a muchos recursos de sesión relacionados de forma simultánea, incluidos los que aún no existen. Puedes restringir el acceso a tus sesiones y eventos para que un usuario solo pueda acceder a su propia información o para que los desarrolladores solo puedan ver ciertos recursos de Session sin permisos especiales.

Antes de comenzar

Para configurar políticas condicionales de Identity and Access Management para sesiones y eventos de sesión, haz lo siguiente:

• Revisa las condiciones de IAM: Familiarízate con la descripción general de las condiciones de IAM.
• Determina los roles necesarios: Identifica qué roles de IAM de sesión especializados son adecuados para tu caso de uso y, así, garantizar el principio de privilegio mínimo.
• Identifica a las entidades principales afectadas: Identifica quiénes de tu organización deberían recibir qué permisos. Por ejemplo, considera lo siguiente:
  • ¿Los usuarios deberían poder ver las sesiones de otros usuarios?
  • ¿Los desarrolladores deberían poder ver todas las sesiones?
  • ¿Los administradores del proyecto deberían poder ver todas las sesiones?
  • ¿Ciertas identidades de agentes deberían poder acceder a ciertas sesiones?
• Otorga roles de IAM: Asegúrate de tener los roles necesarios que contengan los permisos necesarios para realizar las tareas de este documento.

  Para obtener los permisos que necesitas para aplicar condiciones de IAM a los recursos de sesión de Vertex AI Agent Engine , pídele a tu administrador que te otorgue los siguientes roles de IAM:

  • Para proyectos: Administrador de IAM de proyecto (`roles/resourcemanager.projectIamAdmin`)

  Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

  Estos roles predefinidos contienen los permisos necesarios para aplicar condiciones de IAM a los recursos de sesión de Vertex AI Agent Engine. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

  Permisos necesarios

  Se requieren los siguientes permisos para aplicar condiciones de IAM a los recursos de sesión de Vertex AI Agent Engine:

  • Establece acceso condicional a IAM a nivel del proyecto: `resourcemanager.projects.setIamPolicy`

  También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

  Si planeas usar Condiciones de IAM en toda tu organización, también necesitas permisos para administrar las políticas de la organización.

Cómo crear acceso condicional para sesiones

Otorga acceso condicional a las sesiones agregando una condición a una vinculación de política de Identity and Access Management a nivel del proyecto. La condición usa la función api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") para inspeccionar el ID de usuario del recurso de sesión. Defines un ID de usuario cuando creas una sesión.

Para obtener una guía detallada sobre cómo crear políticas de IAM con condiciones, consulta Condiciones en las políticas de permisos.

Para otorgar una sola función a una principal, sigue estos pasos:

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

Prácticas recomendadas para los permisos a nivel del ID de usuario

Cuando crees condiciones para las sesiones, usa las siguientes prácticas recomendadas:

1. Usa roles de IAM de sesión especializados: Las condiciones de IAM de sesión solo se deben usar para los roles que se aplican a las sesiones y los eventos de sesión. Puedes usar roles especializados, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionEditor y aiplatform.googleapis.com/sessionUser, para evitar el acceso demasiado permisivo. Consulta la sección Roles de IAM de sesión especializada para obtener más detalles.

2. Usa condiciones positivas: Te recomendamos que uses condiciones positivas (como verificaciones de igualdad o la presencia de prefijos) en aiplatform.googleapis.com/sessionUserId para obtener una mayor precisión. Dado que los tipos y servicios no admitidos se representan con un ID de usuario vacío, las condiciones negativas (como las verificaciones de desigualdad) pueden coincidir de forma involuntaria con una amplia variedad de recursos, lo que puede ser demasiado permisivo y permitir la concesión inesperada de permisos.

3. Acorta las condiciones si es posible: Te recomendamos que uses la lógica más corta y simple posible en tus expresiones de condiciones de IAM, en especial si planeas tener una gran cantidad de condiciones. Las políticas de permisos de IAM tienen una limitación de tamaño, y simplificar las condiciones evitará que se alcancen las limitaciones de IAM. Consulta Limitaciones para obtener más detalles. Por ejemplo, puedes simplificar la verificación de dos IDs de usuario diferentes combinando la instrucción compuesta api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB', ya que se evalúa con el mismo resultado que la instrucción más corta api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Roles de IAM de sesión especializados

Es fundamental evitar políticas de IAM demasiado permisivas cuando se usan condiciones de IAM. En la siguiente tabla, se enumeran los roles especializados que puedes usar cuando otorgas roles de IAM condicionales para las APIs de sesión:

Usa condiciones de IAM con sesiones

En esta sección, se incluyen los siguientes ejemplos de uso de las condiciones de IAM con sesiones:

1. Otorga acceso de lectura a las sesiones que coinciden exactamente con el ID de usuario.

2. Otorga acceso de escritura a las sesiones que contienen un prefijo específico en el ID del usuario.

3. Otorga acceso completo a las sesiones que contienen uno de los dos IDs de usuario.

Otorga acceso de lectura a las sesiones con concordancia exacta del ID de usuario

La siguiente condición otorga al usuario individual userA@gmail.com acceso de lectura solo a las sesiones que tienen el ID de usuario exacto userA.

Esto significa que la persona tiene la capacidad de obtener sesiones y enumerar los eventos de sesión, siempre y cuando el ID de usuario sea exactamente userA. El usuario no tiene acceso a sesiones con ID de usuario, como userB.

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

Otorga acceso de escritura a las sesiones que contienen un prefijo específico en el ID de usuario.

La siguiente condición otorga al individuo developerA@corp.com acceso de edición a cualquier sesión que contenga el ID de usuario que comienza con user. Puedes usar startsWith para verificar prefijos y endsWith para verificar sufijos.

Esto significa que el desarrollador puede crear, actualizar y borrar sesiones, además de agregar eventos, con IDs de usuario como 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')"
  }
}

Otorga acceso completo a las sesiones que contienen uno de los dos IDs de usuario

La siguiente condición otorga al grupo group:engineering@corp.com acceso de usuario (visualizador y editor) a las sesiones que solo tienen los IDs de usuario 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']"
  }
}

Limitaciones

1. Límite de principales: Las políticas de IAM están limitadas a 1,500 principales únicos. Este límite se puede administrar con grupos de Google. Obtén más información en Límites de todas las principales.

2. Compatibilidad con la API de ListSessions: La API de ListSessions no admite condiciones de IAM. Para otorgar permisos de ListSessions, debes otorgar al principal un rol incondicional, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser o un rol incondicional relevante de Gemini Enterprise Agent Platform.