Rollen & Berechtigungen - Twenty Documentation

Eine Rolle ist ein Berechtigungssatz: welche Objekte eine App lesen oder schreiben kann, welche Felder sie sehen kann und welche plattformbezogenen Funktionen sie nutzen kann. Alle Logikfunktionen und Frontend-Komponenten einer App erben die Berechtigungen der Rolle, die mit defineApplicationRole() markiert ist (siehe Die Standardfunktionsrolle unten).

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,
  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.APPLICATIONS],
});

Zeilenbasierte Sicherheit

Objekt- und Feldberechtigungen legen fest, auf welche Objekte und Felder eine Rolle zugreifen kann. Zeilenbasierte Berechtigungsprädikate gehen noch weiter und legen fest, welche Datensätze eine Rolle sehen und bearbeiten kann — zum Beispiel eine Self-Service-Rolle, bei der jeder externe Benutzer nur seine eigenen Datensätze sieht. Deklarieren Sie Prädikate mit rowLevelPermissionPredicates für die Rolle. Wie beim Rest des Manifests hat jedes Prädikat einen eigenen universalIdentifier und referenziert ein Objekt und ein Feld über deren universalIdentifier; außerdem besitzt es einen operand und (optional) ein workspaceMember-Feld, dessen Wert zur Abfragezeit injiziert wird — sodass Sie ausdrücken können: “Die Eigentümerbeziehung des Datensatzes ist das aktuelle workspaceMember”:

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,
    },
  ],
});

Da Prädikate im Manifest ausgeliefert werden, werden sie zusammen mit der Rolle bei jeder Installation und jedem Upgrade erstellt, aktualisiert und entfernt – es ist kein separater Post-Installationsschritt erforderlich, um sie zu synchronisieren.

Kombinieren von Prädikaten mit Gruppen

Standardmäßig werden die Prädikate einer Rolle mit AND verknüpft. Um einige von ihnen mit OR zu verknüpfen (oder um Logik zu verschachteln), deklarieren Sie einen Eintrag rowLevelPermissionPredicateGroups und verweisen Sie von jedem Prädikat aus über predicateGroupUniversalIdentifier darauf. Diese Rolle ermöglicht es einem Partner, eine Opportunity zu sehen, deren er entweder Eigentümer oder der Ansprechpartner ist:

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',
    },
  ],
});

Notizen:

Geben Sie jedem Prädikat und jeder Gruppe einen stabilen universalIdentifier (beliebige uuid) – er identifiziert die Entität über Upgrades hinweg eindeutig, und Prädikate verweisen über ihn auf Gruppen.
Prädikate können auf Objekte und Felder verweisen, die Ihrer App gehören, oder auf Standardobjekte von Twenty.
Zeilenbasierte Sicherheit wird für Workspaces in Tarifen durchgesetzt, die sie enthalten; die Prädikate werden auch in anderen Tarifen weiterhin synchronisiert, sie werden dort einfach nicht durchgesetzt.

Die Standard-Funktionsrolle

Wenn Sie eine neue App erzeugen, erstellt die CLI eine Datei für die Standardrolle, die mit defineApplicationRole() deklariert ist:

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() ist ein dünner Wrapper um defineRole(), der die Rolle kennzeichnet, die zum Installationszeitpunkt als Standardrolle Ihrer Anwendung verwendet wird. Die Validierung ist identisch zu defineRole, aber die Build-Pipeline verdrahtet deren universalIdentifier automatisch in das defaultRoleUniversalIdentifier des Anwendungsmanifests – sodass Sie es nicht selbst aus defineApplication referenzieren müssen. Notizen:

Genau eine defineApplicationRole(...) ist pro App zulässig – der Manifest-Build schlägt fehl, wenn mehr als eine gefunden wird.
Verwenden Sie defineRole() (nicht defineApplicationRole()) für alle zusätzlichen Rollen, die Ihre App mitliefert.
Das explizite Setzen von defaultRoleUniversalIdentifier in defineApplication() wird für die Abwärtskompatibilität weiterhin unterstützt, ist aber zugunsten von defineApplicationRole() veraltet.

Beste Praktiken

Beginnen Sie mit der vorgegebenen Rolle und schränken Sie sie dann schrittweise ein – standardmäßig wird umfangreicher Lesezugriff gewährt, was selten das ist, was Sie in Produktionsumgebungen möchten.
Ersetzen Sie objectPermissions und fieldPermissions durch die genauen Objekte und Felder, die Ihre Funktionen tatsächlich benötigen.
permissionFlagUniversalIdentifiers steuern den Zugriff auf Funktionen auf Plattformebene. Halten Sie sie minimal.
Ein funktionierendes Beispiel finden Sie unter: hello-world/src/roles/function-role.ts.

​Zeilenbasierte Sicherheit

​Kombinieren von Prädikaten mit Gruppen

​Die Standard-Funktionsrolle

​Beste Praktiken

Zeilenbasierte Sicherheit

Kombinieren von Prädikaten mit Gruppen

Die Standard-Funktionsrolle

Beste Praktiken