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
En la consola de Google Cloud , dirígete a la página IAM.
Elige tu proyecto.
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.como//iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.
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.
Agrega una condición al rol con
aiplatform.googleapis.com/sessionUserIdcomo el atributo de la API. Consulta los ejemplos que aparecen a continuación para ver algunas declaraciones de condiciones posibles.Haz clic en Guardar. A la principal se le otorga la función en el recurso.
gcloud
-
En la consola de Google Cloud , 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.
-
El comando
add-iam-policy-bindingte 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, comomy-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.comoprincipalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com. Para obtener una lista completa de los valores que puede tenerPRINCIPAL, 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.
- Roles predefinidos:
-
CONDITION: Agrega una condición al rol conaiplatform.googleapis.com/sessionUserIdcomo 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, comomy-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 tenerMEMBER, consulta Identificadores de principales. -
CONDITION: Es tu declaración de condición de IAM que usaaiplatform.googleapis.com/sessionUserIdcomo 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:
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/sessionEditoryaiplatform.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.Usa condiciones positivas: Te recomendamos que uses condiciones positivas (como verificaciones de igualdad o la presencia de prefijos) en
aiplatform.googleapis.com/sessionUserIdpara 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.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 cortaapi.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. |
|
roles/aiplatform.sessionEditor |
Otorga acceso de escritura a las sesiones y los eventos anexados. |
|
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:
Otorga acceso de lectura a las sesiones con coincidencia exacta del ID de usuario.
Otorga acceso de escritura a las sesiones que contengan un prefijo específico en el ID del usuario.
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
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.
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, comoaiplatform.googleapis.com/sessionViewer,aiplatform.googleapis.com/sessionUsero un rol relevante incondicional de Gemini Enterprise Agent Platform.