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 las sesiones de Agent Platform.

Descripción general

Las condiciones de IAM te permiten otorgar acceso a los recursos de sesión y de 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 de sesión con el atributo de la API aiplatform.googleapis.com/sessionUserId con 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 de proyecto y se aplican a todas las sesiones y los 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 aquellos 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 sesión sin otorgar 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 para garantizar el principio de privilegio mínimo.
  • Identifica las principales afectadas: Identifica quién en tu organización debe 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 de proyectos deberían poder ver todas las sesiones?
    • ¿Deberían ciertas identidades de agentes poder acceder a determinadas sesiones?
  • Otorga roles de IAM: Asegúrate de tener los roles necesarios que contengan los permisos que necesitas para realizar las tareas de este documento.

    Para obtener los permisos que necesitas para aplicar condiciones de IAM a los recursos de sesiones de la plataforma de agentes , pídele a tu administrador que te otorgue los siguientes roles de IAM:

    • Para proyectos: Administrador de IAM del 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 sesiones de la plataforma de agentes . Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

    Permisos necesarios

    Se requieren los siguientes permisos para aplicar las condiciones de IAM a los recursos de sesiones de Agent Platform :

    • Establece el acceso condicional de IAM a nivel de 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.

Crea acceso condicional para las 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. Debes definir 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:

Console

  1. En la consola de Google Cloud , dirígete a la página IAM.

    Ir a IAM

  2. Elige tu proyecto.

  3. Selecciona una principal para otorgarle una función:

    • Para otorgar un rol a una principal que ya tenga otros roles en el recurso, busca una fila que contenga la principal y haz clic en Editar principal en esa fila y en Agregar otro rol.

      Para otorgar un rol a un agente de servicio, selecciona la casilla de verificación Incluir asignaciones de roles proporcionadas por Google para ver su dirección de correo electrónico.

    • Para otorgar un rol a una principal que aún no tenga otros roles en el recurso, haz clic en Otorgar acceso y, luego, ingresa un identificador de principal. Por ejemplo, my-user@example.com o //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.

  4. Elige un rol para otorgar de la lista desplegable. Para una mejor seguridad, elige una función que incluya solo los permisos que necesita tu principal. Puedes elegir uno de los roles de IAM de sesión especializados.

  5. Agrega una condición al rol con aiplatform.googleapis.com/sessionUserId como el atributo de la API. Consulta los ejemplos que aparecen a continuación para ver algunas declaraciones de condiciones posibles.

  6. Haz clic en Guardar. A la principal se le otorga la función en el recurso.

gcloud

  1. En la consola de Google Cloud , activa Cloud Shell.

    Activa Cloud Shell

    En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.

  2. El comando add-iam-policy-binding te permite otorgarle un rol a una principal con rapidez.

    Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud . Los IDs de proyecto son alfanuméricos, como my-project.

    • PRINCIPAL: Un identificador para la principal o el miembro, que suele tener el siguiente formato: PRINCIPAL_TYPE:ID. Por ejemplo, user:my-user@example.com o principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Para obtener una lista completa de los valores que puede tener PRINCIPAL, consulta Identificadores de principales.

      Para el tipo de principal user, el nombre de dominio en el identificador debe ser un dominio de Google Workspace o de Cloud Identity. Para obtener información sobre cómo configurar un dominio de Cloud Identity, consulta la descripción general de Cloud Identity.

    • ROLE_NAME: El nombre del rol que deseas revocar. Usa uno de los siguientes formatos:

      • Roles predefinidos: roles/aiplatform.IDENTIFIER
      • Roles personalizados a nivel de proyecto: projects/PROJECT_ID/roles/IDENTIFIER

      Elige un rol para otorgar de la lista desplegable. Para una mayor seguridad, elige un rol que incluya solo los permisos que necesita la principal. Puedes elegir uno de los roles de IAM de sesión especializados.

    • CONDITION: Agrega una condición al rol con aiplatform.googleapis.com/sessionUserId como el atributo de la API. Consulta los ejemplos que aparecen a continuación para ver algunas declaraciones de condiciones posibles.

    Ejecuta el siguiente 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 respuesta contiene la política de IAM actualizada.

Terraform

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform. Para obtener más información, consulta la documentación de referencia del proveedor de Terraform.

Si usas Terraform para configurar tus políticas de IAM, puedes incluir una condición en el recurso google_project_iam_member para restringir el acceso de un miembro a las sesiones.

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

Reemplaza las siguientes variables:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud . Los IDs de proyecto son alfanuméricos, como my-project.
  • ROLE: Es el rol de IAM que se otorgará, por ejemplo, roles/aiplatform.sessionEditor.
  • MEMBER: Es la principal a la que se le otorgará el rol, por ejemplo, user:developerA@corp.com. Para obtener una lista completa de los valores que puede tener MEMBER, consulta Identificadores de principales.
  • CONDITION: Es tu declaración de condición de IAM que usa aiplatform.googleapis.com/sessionUserId como el atributo de la API. Consulta los ejemplos que aparecen a continuación para ver algunas declaraciones de condiciones posibles.

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 gama de recursos, lo que puede ser demasiado permisivo y permitir el otorgamiento de permisos inesperados.

  3. Acorta las condiciones si es posible: Te recomendamos que uses la lógica más corta y simple dentro de tus expresiones de condición 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 produzcan 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 sentencia 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 sentencia más corta api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB'].

Roles de IAM de sesión especializados

Es fundamental evitar las políticas de IAM demasiado permisivas cuando se usan las 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:

Nombre del rol Descripción Permisos incluidos
roles/aiplatform.sessionViewer Otorga acceso de solo lectura a las sesiones y los eventos de fichas.
  • aiplatform.googleapis.com/sessions.get
  • aiplatform.googleapis.com/sessions.list
  • aiplatform.googleapis.com/sessionEvents.list
roles/aiplatform.sessionEditor Otorga acceso de escritura a las sesiones y los eventos anexados.
  • aiplatform.googleapis.com/sessions.create
  • aiplatform.googleapis.com/sessions.update
  • aiplatform.googleapis.com/sessions.delete
  • aiplatform.googleapis.com/sessionEvents.append
roles/aiplatform.sessionUser Otorga acceso completo a las sesiones y los eventos, incluidos todos los permisos de visualizador y editor. Incluye todos los permisos de sessionEditor y sessionViewer.

Usa condiciones de IAM con sesiones

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

  1. Otorga acceso de lectura a las sesiones con coincidencia exacta del ID de usuario.

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

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

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

La siguiente condición otorga a la persona 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 que el ID de usuario sea exactamente userA. El usuario no tiene acceso a las sesiones con el 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 a la persona developerA@corp.com acceso de edición a cualquier sesión que contenga el ID de usuario que comience con user. Puedes usar startsWith para la verificación de prefijos y endsWith para la verificación de sufijos.

Esto significa que el desarrollador tiene la capacidad de 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 contengan uno de dos IDs de usuario

La siguiente condición otorga al usuario del grupo group:engineering@corp.com (visualizador y editor) acceso 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 únicas. Este límite se puede administrar con los Grupos de Google. Consulta 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 ListSessions, debes otorgar a la principal un rol incondicional, como aiplatform.googleapis.com/sessionViewer, aiplatform.googleapis.com/sessionUser o un rol relevante incondicional de Gemini Enterprise Agent Platform.