Roles y permisos

Resumen

Un rol es un conjunto de permisos: qué objetos puede leer o escribir una aplicación, qué campos puede ver y qué capacidades a nivel de plataforma puede usar. Las funciones lógicas y los componentes de interfaz de cada aplicación heredan los permisos del rol marcado con defineApplicationRole() (consulta El rol de función predeterminado más abajo).

src/roles/restricted-company-role.ts

import {
  defineRole,
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
  SystemPermissionFlag,
} from 'twenty-sdk/define';

export default defineRole({
  universalIdentifier: '2c80f640-2083-4803-bb49-003e38279de6',
  label: 'My new role',
  description: 'A role that can be used in your workspace',
  canReadAllObjectRecords: false,
  canUpdateAllObjectRecords: false,
  canSoftDeleteAllObjectRecords: false,
  canDestroyAllObjectRecords: false,
  canUpdateAllSettings: false,
  canAccessAllAgentChatChannels: false,
  canBeAssignedToAgents: false,
  canBeAssignedToUsers: false,
  canBeAssignedToApiKeys: false,
  objectPermissions: [
    {
      objectUniversalIdentifier:
        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
      canReadObjectRecords: true,
      canUpdateObjectRecords: true,
      canSoftDeleteObjectRecords: false,
      canDestroyObjectRecords: false,
    },
  ],
  fieldPermissions: [
    {
      objectUniversalIdentifier:
        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
      fieldUniversalIdentifier:
        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name
          .universalIdentifier,
      canReadFieldValue: false,
      canUpdateFieldValue: false,
    },
  ],
  permissionFlagUniversalIdentifiers: [SystemPermissionFlag.WORKSPACE_APPS],
});

SystemPermissionFlag.USER_APPS y SystemPermissionFlag.WORKSPACE_APPS están disponibles a partir de twenty-sdk 2.54; las versiones anteriores los denominan CONNECTED_ACCOUNTS y APPLICATIONS. Los nombres antiguos son alias obsoletos para los mismos indicadores, y un rol conserva cada indicador una sola vez. La enumeración de SystemPermissionFlag, por ejemplo con Object.keys, sigue mostrando los nombres antiguos. La API también informa de estos indicadores con sus claves antiguas, por ejemplo en currentUserWorkspace.permissionFlags.

Seguridad a nivel de fila

Los permisos a nivel de fila requieren el plan Organization o superior — consulta precios. Lo que sucede en un plan sin el derecho se explica en las notas al final de esta sección. Los permisos de objetos y campos determinan a qué objetos y campos puede acceder o modificar un rol. Los predicados de permisos a nivel de fila van más allá y deciden qué registros puede ver y sobre los que puede actuar un rol; por ejemplo, un rol de autoservicio en el que cada usuario externo ve solo sus propios registros. Declara los predicados con rowLevelPermissionPredicates en el rol. Como el resto del manifiesto, cada predicado tiene su propio universalIdentifier y hace referencia a un objeto y a un campo mediante su universalIdentifier, a un operand y, de forma opcional, a un campo workspaceMember cuyo valor se inyecta en tiempo de consulta, de modo que puedas expresar: “la relación de propietario del registro es el miembro actual del espacio de trabajo”:

src/roles/partner-role.ts

import {
  defineRole,
  RowLevelPermissionPredicateOperand,
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';

import { ACCOUNT_OWNER_FIELD_UNIVERSAL_IDENTIFIER } from '../fields/account-owner.field';

export default defineRole({
  universalIdentifier: 'c3c1dc2e-1a08-4de5-abb7-2139b3d99343',
  label: 'Partner',
  description: 'External partner — sees only its own records',
  canBeAssignedToUsers: true,
  objectPermissions: [
    {
      objectUniversalIdentifier:
        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
      canReadObjectRecords: true,
      canUpdateObjectRecords: true,
    },
  ],
  rowLevelPermissionPredicates: [
    {
      universalIdentifier: 'd0f0c1a2-3b4c-4d5e-8f60-111111111111',
      objectUniversalIdentifier:
        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
      fieldUniversalIdentifier: ACCOUNT_OWNER_FIELD_UNIVERSAL_IDENTIFIER,
      operand: RowLevelPermissionPredicateOperand.IS,
      workspaceMemberFieldUniversalIdentifier:
        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.workspaceMember.fields.id
          .universalIdentifier,
    },
  ],
});

Debido a que los predicados se envían en el manifiesto, se crean, actualizan y eliminan junto con el rol en cada instalación y actualización; no hay ningún paso posterior a la instalación independiente que mantener sincronizado.

Combinar predicados con grupos

De forma predeterminada, los predicados de un rol se combinan con AND. Para combinar algunos de ellos con OR (o para anidar lógica), declara una entrada rowLevelPermissionPredicateGroups y haz que cada predicado apunte a ella mediante predicateGroupUniversalIdentifier. Este rol permite que un socio vea una Oportunidad de la que es propietario o de la que es el punto de contacto:

src/roles/partner-opportunities-role.ts

import {
  defineRole,
  RowLevelPermissionPredicateGroupLogicalOperator,
  RowLevelPermissionPredicateOperand,
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';

const OPPORTUNITY = STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.opportunity;
const CURRENT_MEMBER =
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.workspaceMember.fields.id
    .universalIdentifier;

export default defineRole({
  universalIdentifier: 'b2a1c0d9-8e7f-4a6b-9c5d-222222222222',
  label: 'Partner (opportunities)',
  canBeAssignedToUsers: true,
  objectPermissions: [
    {
      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
      canReadObjectRecords: true,
    },
  ],
  rowLevelPermissionPredicateGroups: [
    {
      universalIdentifier: 'c3b2a1d0-9f8e-4b7a-8d6c-333333333333',
      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
      logicalOperator: RowLevelPermissionPredicateGroupLogicalOperator.OR,
    },
  ],
  rowLevelPermissionPredicates: [
    {
      universalIdentifier: 'd4c3b2a1-0e9f-4c8b-9e7d-444444444444',
      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
      fieldUniversalIdentifier: OPPORTUNITY.fields.owner.universalIdentifier,
      operand: RowLevelPermissionPredicateOperand.IS,
      workspaceMemberFieldUniversalIdentifier: CURRENT_MEMBER,
      predicateGroupUniversalIdentifier: 'c3b2a1d0-9f8e-4b7a-8d6c-333333333333',
    },
    {
      universalIdentifier: 'e5d4c3b2-1f0e-4d9c-8f8e-555555555555',
      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
      fieldUniversalIdentifier:
        OPPORTUNITY.fields.pointOfContact.universalIdentifier,
      operand: RowLevelPermissionPredicateOperand.IS,
      workspaceMemberFieldUniversalIdentifier: CURRENT_MEMBER,
      predicateGroupUniversalIdentifier: 'c3b2a1d0-9f8e-4b7a-8d6c-333333333333',
    },
  ],
});

Notas:

Asigna a cada predicado y grupo un universalIdentifier estable (cualquier uuid): sirve como clave de la entidad a través de las actualizaciones, y los predicados hacen referencia a los grupos mediante él.
Los predicados pueden hacer referencia a objetos y campos que sean propiedad de tu aplicación o de los objetos estándar de Twenty.
La seguridad a nivel de fila se aplica a los espacios de trabajo en el plan Organization o superior. En otros planes, los predicados declarados en un manifiesto de app se siguen sincronizando; simplemente no se aplican.
La API de metadatos se comporta de manera diferente al manifiesto en este caso: sin el derecho, upsertRowLevelPermissionPredicates se rechaza con ROW_LEVEL_PERMISSION_FEATURE_DISABLED en lugar de sincronizarse. Por lo tanto, un espacio de trabajo en un plan que no incluye seguridad a nivel de fila no puede crear predicados fuera de un manifiesto de app, aunque el campo rowLevelPermissionPredicates está presente en el tipo Role al inspeccionar el esquema.

El rol de función predeterminado

Cuando generas una nueva aplicación, la CLI crea un archivo de rol predeterminado declarado con defineApplicationRole():

src/roles/default-role.ts

import { defineApplicationRole } from 'twenty-sdk/define';

export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
  'b648f87b-1d26-4961-b974-0908fd991061';

export default defineApplicationRole({
  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  label: 'Default function role',
  description: 'Default role for function Twenty client',
  canReadAllObjectRecords: true,
  canUpdateAllObjectRecords: false,
  canSoftDeleteAllObjectRecords: false,
  canDestroyAllObjectRecords: false,
  canUpdateAllSettings: false,
  canBeAssignedToAgents: false,
  canBeAssignedToUsers: false,
  canBeAssignedToApiKeys: false,
  objectPermissions: [],
  fieldPermissions: [],
  permissionFlagUniversalIdentifiers: [],
});

defineApplicationRole() es una envoltura ligera alrededor de defineRole() que marca el rol utilizado como predeterminado de tu aplicación en el momento de la instalación. La validación es idéntica a defineRole, pero la canalización de compilación conecta automáticamente su universalIdentifier con defaultRoleUniversalIdentifier del manifiesto de la aplicación, por lo que no necesitas hacer referencia a él desde defineApplication. Notas:

Se permite exactamente una llamada a defineApplicationRole(...) por aplicación; la compilación del manifiesto fallará si encuentra más de una.
Usa defineRole() (no defineApplicationRole()) para cualquier rol adicional que distribuya tu aplicación.
Configurar defaultRoleUniversalIdentifier explícitamente en defineApplication() sigue siendo compatible por motivos de retrocompatibilidad, pero está en desuso en favor de defineApplicationRole(). También puede nombrar un rol que su aplicación no define, como el rol predeterminado integrado de la aplicación personalizada del espacio de trabajo que conserva twenty app pull; en ese caso, la compilación no puede comprobar ese rol, por lo que debe existir en el espacio de trabajo de destino.
Un rol al que se pueden asignar miembros del espacio de trabajo o claves de API (canBeAssignedToUsers o canBeAssignedToApiKeys, ambos true cuando se omiten) es un rol personalizado y requiere el plan Organization o superior: en otros planes, se rechaza la instalación. Mantén ambos en false en los roles que solo tu aplicación y sus agentes asumen.

Roles de Agente

El rol de aplicación es lo que un espacio de trabajo revisa al instalar tu aplicación, por lo que debe abarcar todo lo que la propia aplicación puede hacer. Cualquier rol que asignes a un agente mediante roleUniversalIdentifier en defineAgent() no debe otorgar más que el rol de aplicación: ninguna acción de objeto, acceso a campos, indicador de permiso o ámbito de nivel de fila que el rol de aplicación no tenga. Si lo hace, la compilación falla con un error que enumera las concesiones excedentes. Los roles que tu aplicación distribuye para miembros del espacio de trabajo o claves de API no están sujetos a esta regla, ya que la aplicación nunca se ejecuta con ellos. La comprobación necesita el rol de aplicación en el código fuente de su aplicación, por lo que se omite cuando el rol predeterminado se define en otro lugar.

Mejores prácticas

Parte del rol generado automáticamente y luego restríngeelo progresivamente; el valor predeterminado concede un acceso amplio de lectura, lo cual rara vez es lo que quieres en producción.
Reemplaza objectPermissions y fieldPermissions con los objetos y campos que realmente necesitan tus funciones.
permissionFlagUniversalIdentifiers controla el acceso a capacidades a nivel de plataforma. Manténlos al mínimo.
Una marca de permiso que tu aplicación declara con definePermissionFlag() tiene un permissionType: 'tool' (el valor predeterminado) para una capacidad que se puede conceder a un agente o a un usuario, 'settings' para una marca que desbloquea un área de configuración.
Consulta un ejemplo funcional: examples/hello-world/src/roles/default-role.ts.

Desarrolladores

Aplicaciones

API

Autoalojamiento

Contribuir

Biblioteca de IU

Resumen

Seguridad a nivel de fila

Combinar predicados con grupos

El rol de función predeterminado

Roles de Agente

Mejores prácticas

​Resumen

​Seguridad a nivel de fila

​Combinar predicados con grupos

​El rol de función predeterminado

​Roles de Agente

​Mejores prácticas

Resumen

Seguridad a nivel de fila

Combinar predicados con grupos

El rol de función predeterminado

Roles de Agente

Mejores prácticas