Permission Manager

Der Permission Manager verwaltet Berechtigungen auf Objekten im Dateisystem und auf Anhängen von Workflows. Sie legen fest, welche Benutzer und Gruppen ein Objekt lesen, bearbeiten oder vollständig verwalten dürfen. Das System setzt diese Vorgaben im Hintergrund in ACLs um. Der Permission Manager ist Teil von agorum core open.

Diese Dokumentation erklärt zuerst die Grundlagen, dann die Arbeit mit dem Permission Manager, seine Konfiguration und die Verwaltung per Skript.

Grundlagen

Berechtigungsstufen

Der Permission Manager kennt diese Berechtigungsstufen. Die Oberfläche und die Skript-Funktionen verwenden die technischen Werte in der linken Spalte.

Stufe	Bedeutung
read	Objekt sehen und Inhalt lesen.
write	Lesen, Inhalt und Attribute ändern, Objekt sperren, Mitglieder, Elemente, Beziehungen, Versionsserien und Versionen hinzufügen und entfernen. Nicht enthalten: Löschen und Berechtigen.
all	Wie write, zusätzlich Löschen und Berechtigen.
check_out	Lesen, Objekt sperren und eine neue Version hinzufügen (Dokumente auschecken).
protected	Lesen sowie Elemente und Verknüpfungen (Beziehungen) hinzufügen und entfernen.
none	Keine Berechtigung. Damit entziehen Sie einem Mitglied die geerbten Berechtigungen, ohne ihm neue zu geben.

Vererbung

Berechtigungen werden von übergeordneten Objekten vererbt. Eine direkt am Objekt gesetzte Regel ersetzt die geerbten Regeln desselben Mitglieds auf allen Stufen. Mit none nehmen Sie einem Mitglied deshalb die geerbten Rechte, ohne neue zu vergeben.

Die Vererbung einer Berechtigung lässt sich an einem Objekt unterbrechen. In der Oberfläche gibt es Vererbung unterbrechen nur, wenn die Einstellung enhancedFeatures auf true steht (Standard: false, siehe Konfiguration). Per Skript geht es immer, siehe Vererbung unterbrechen im Abschnitt zur Skript-Verwaltung.

Basis-ACL, Scope-ACLs und Entity-ACLs

Der Permission Manager legt Berechtigungen nicht direkt am Objekt ab, sondern setzt sie als ACLs um:

• Jedes verwaltete Objekt hat eine Basis-ACL, eine eigene oder eine geerbte. Ohne Basis-ACL entstehen keine ACLs. Der Worker nimmt nur Objekte an, die eine Basis-ACL haben. Die Regeln sind dann zwar gespeichert und ablesbar, wirken aber nicht. Außerdem bearbeitet der Worker nur Objekte im Dateisystem und lässt Objekte aus, die das Systemflag „keine Änderung“ tragen.
• Zusätzlich setzt der Permission Manager Scope-ACLs auf das Objekt. Einem Objekt können beliebig viele Scope-ACLs zugewiesen werden.
• Die Scope-ACLs erzeugt er als Entity-ACLs: je Benutzer oder Gruppe und Berechtigungsstufe eine ACL. Das System legt sie automatisch an und verwaltet sie. Bearbeiten Sie sie nicht von Hand. Administratoren sind von diesen ACLs nicht ausgenommen. Für die Stufe none entsteht keine ACL: Sie entzieht geerbte Rechte über negative Metadaten.

Zwei Basis-ACLs stehen bereit:

ACL	Wirkung
private-admin-affected	Administratoren sind von der ACL betroffen und müssen wie andere Benutzer berechtigt werden. Standard.
private-non-admin-affected	Administratoren haben immer Vollzugriff.

Die Entity-ACLs tragen die UUID des Benutzers oder der Gruppe im Namen, nicht deren Namen:

Namensschema	Beispiel
ACL_USER_SYS_PM_<STUFE>_<UUID>	ACL_USER_SYS_PM_READ_71aa7bf1-ce62-11e0-b47a-0800276e2399
ACL_GROUP_SYS_PM_<STUFE>_<UUID>	ACL_GROUP_SYS_PM_READ_<UUID der Gruppe>

SYS_PM steht für Berechtigungen im Dateisystem, SYS_ACW_PERMISSION für Berechtigungen auf Workflow-Anhängen. Beide sind Bestandteile des Namens, keine Präfixe.

Mit dem Permission Manager arbeiten

Wo Sie den Permission Manager verwenden

• Im Explorer: Das Detailfenster eines Objekts enthält die Registerkarte Rechte. Sie zeigt die Basis-ACL und die Scope-ACLs des Objekts, auch solche, die nicht vom Permission Manager stammen. Zu jedem Mitglied stehen dort die ACL und die ermittelte Stufe, ACLs ohne Mitglieder erscheinen nur mit ihrem Namen. Wie Sie Berechtigungen über die Administration verwalten, beschreibt Berechtigungen in der Administration verwalten.
• Im Dateisystem: Berechtigungen auf Ordnern und Dateien.
• In Workflows: Berechtigungen auf den Anhängen eines Workflows, auch rekursiv auf Ordner.

Zugriff auf die Registerkarte „Rechte“

Die Registerkarte Rechte im Detailfenster sehen die Mitglieder der ACL ACL_PAI_PERMISSIONS_. Nehmen Sie Benutzer oder Gruppen, die die Registerkarte sehen sollen, in diese ACL auf, siehe Erste Schritte für Administratoren. Die Rechte am Objekt selbst spielen dafür keine Rolle.

Berechtigungen auf Objekten prüfen

Welche Berechtigungen ein Benutzer an einem Objekt tatsächlich hat, zeigt der Berechtigungsprüfer.

Berechtigungen auf Workflow-Anhängen

Die Berechtigungen auf den Anhängen eines Workflows setzt der Permission Manager nach einem eigenen Weg. Die Vorgaben stehen nicht an den Anhängen, sondern an den Tokens des Workflows, in diesen Metadaten:

Metadatum am Token	Stufe
sys_acw_attachmentPermissionRead	read
sys_acw_attachmentPermissionWrite	write
sys_acw_attachmentPermissionAll	all
sys_acw_attachmentPermissionProtected	protected
sys_acw_attachmentPermissionCheckout	check_out

• Für jedes Mitglied legt der Permission Manager eine Scope-ACL auf den Anhang. Ist der Anhang ein Ordner, setzt er sie auf alle enthaltenen Objekte.
• Ist ein Anhang an mehrere Workflows angehängt, gelten die Berechtigungen aller Tokens zusammen.
• Hängt der Anhang an keinem Token mehr, entfernt der Permission Manager die Workflow-ACLs wieder.
• Die Stufe none und die Basis-ACL gibt es für Workflow-Anhänge nicht.

Die Rechte auf Anhänge vergeben Sie in den Interaktionsknoten des Workflows. Welche Knoten das sind und wie Sie die Rechte per Expression setzen, beschreibt Rechte auf Anhänge (Attachments) vergeben.

Gelöschte Benutzer und Gruppen

Verweist eine Berechtigungsregel auf einen Benutzer oder eine Gruppe, den oder die es nicht mehr gibt, ignoriert der Permission Manager sie bei der Verarbeitung. Er überspringt die Regel und wendet die übrigen Regeln des Objekts weiter an. Die Verarbeitung bricht dadurch nicht ab. Übersprungen wird eine Regel außerdem, wenn ihr Ziel weder Benutzer noch Gruppe ist oder die Berechtigung dem System unbekannt ist.

Für jede übersprungene Regel legt das System einen Sticky-Eintrag im Log des Permission Workers an. Sticky-Einträge zeigt das Support Tool gesondert an, siehe Dashboard. Der Eintrag enthält das betroffene Objekt, den Benutzer oder die Gruppe, die Berechtigung und den Grund, warum die Regel nicht anwendbar ist.

1. Öffnen Sie den Sticky-Eintrag im Support Tool und das Objekt, auf das er verweist.
2. Korrigieren Sie die Regel des Permission Managers: Ersetzen Sie den gelöschten Benutzer oder die gelöschte Gruppe durch einen vorhandenen.

Das System nimmt den Eintrag selbst zurück, sobald das Objekt ohne diese Regel erneut berechtigt wird, etwa weil Sie die Regel ersetzt haben, oder wenn das Objekt nicht mehr existiert.

Konfiguration und Metadaten

Konfiguration

Die Konfiguration liegt in der MetaDB unter MAIN_MODULE_MANAGEMENT/customers/permission-manager. Nicht gesetzte Einstellungen nehmen den Standardwert.

Schlüssel	Beschreibung	Standard
enhancedFeatures	Aktiviert erweiterte Funktionen. Nur damit zeigt die Oberfläche Vererbung unterbrechen.	false
baseAcl/acl	Basis-ACL, die die Oberfläche bei neuen Regeln vorgibt. Ist baseAcl/editable auf false gesetzt, zeigt der gesperrte Schalter diesen Wert. Die Oberfläche kennt nur private-admin-affected und private-non-admin-affected, jeden anderen Namen zeigt sie als private-admin-affected.	private-admin-affected
baseAcl/editable	Legt fest, ob Benutzer die Basis-ACL in der Oberfläche ändern dürfen. Bei false ist der Schalter gesperrt.	true
exportPath	Pfad für den JSON-Export.	/agorum/roi/workspace/permission-manager/export
handler	Registrierte eigene Permission-Handler. Jeder Eintrag verweist mit script auf ein Skript.	–
grantees	Datenquelle für die Auswahl von Benutzern und Gruppen (Type: user-group).	user-group

Metadaten

Der Permission Manager speichert seine Vorgaben in Metadaten mit dem Präfix sys_pm_. Sie werden an Unterobjekte vererbt, außer sys_pm_defined und sys_pm_toentitle_boolean.

Metadatum	Beschreibung
sys_pm_read	Benutzer und Gruppen mit Lesezugriff
sys_pm_write	Benutzer und Gruppen mit Schreibzugriff
sys_pm_all	Benutzer und Gruppen mit Vollzugriff
sys_pm_check_out	Benutzer und Gruppen mit dem Recht zum Auschecken
sys_pm_protected	Benutzer und Gruppen mit geschütztem Zugriff
sys_pm_none	Benutzer und Gruppen, denen die Berechtigung ausdrücklich entzogen ist
sys_pm_base	UUID der Basis-ACL des Objekts
sys_pm_defined	JSON mit den Regeln, die am Objekt selbst verwaltet werden (nicht vererbt)
sys_pm_toentitle_boolean	Markierung für den Worker: Das Objekt muss berechtigt werden (nicht vererbt)

Berechtigungen per Skript verwalten

Die JavaScript-Bibliothek common/permissions setzt und entfernt objektspezifische Berechtigungen über den Permission Manager. Entity-ACLs und Scope-ACLs auf Objekten beschreibt common/objects.

Die Funktionen nehmen jede Objekt-ID an, zum Beispiel eine UUID, einen Pfad oder user:demo. Auch bei granteeId wandelt der Permission Manager die ID intern in die UUID um. Die Funktionen prüfen nicht, ob der Benutzer oder die Gruppe existiert. Eine unbekannte ID bleibt unverändert stehen, die Regel wird trotzdem gespeichert und später übersprungen, siehe Gelöschte Benutzer und Gruppen. Erlaubte Berechtigungen sind none, read, write, all, check_out und protected.

Basis-ACL setzen und lesen

Mit setBaseAcl setzen Sie die Basis-ACL anhand des ACL-Namens, mit getBaseAcl lesen Sie ihren Namen. Untergeordnete Objekte erben sie, solange sie keine eigene haben. Ist am Objekt keine Basis-ACL gesetzt, liefert getBaseAcl die vererbte oder, wenn es keine gibt, eine leere Zeichenkette. Per Skript akzeptiert setBaseAcl jede vorhandene ACL. Die Oberfläche bietet nur private-admin-affected und private-non-admin-affected an. Die Funktionen sind auch in der Bibliothek common/permissions beschrieben.

let objects = require('common/objects');
let permissions = require('common/permissions');

let folder = objects.find('/agorum/roi/Files/Beispielordner');

permissions.setBaseAcl(folder.UUID, 'private-admin-affected');
let aclName = permissions.getBaseAcl(folder.UUID);
// 'private-admin-affected'

Berechtigung für einen Benutzer setzen

Das Beispiel setzt die Basis-ACL und gibt dem Benutzer demo danach Leserecht auf dem Ordner. Es lässt sich immer nur eine Berechtigung auf einmal setzen. Mehrere Berechtigungen setzen Sie nacheinander.

let objects = require('common/objects');
let permissions = require('common/permissions');

let folder = objects.find('/agorum/roi/Files/Beispielordner');
let demo = objects.find('user:demo');

permissions.setBaseAcl(folder.UUID, 'private-admin-affected');
permissions.setPermission(folder.UUID, {
  granteeId: demo.UUID,
  permission: 'read'
});

Der Permission Manager legt die ACLs einige Sekunden später an. Wie die Entity-ACLs heißen, steht im Abschnitt Basis-ACL, Scope-ACLs und Entity-ACLs.

Berechtigungen auslesen

Das Beispiel listet die Namen aller Benutzer und Gruppen auf, denen am Ordner direkt das Leserecht gesetzt ist. getPermissions liefert eine Liste mit Einträgen der Form granteeId (UUID des Benutzers oder der Gruppe) und permission. Vererbte Berechtigungen enthält die Liste nicht. Ist nichts gesetzt, ist sie leer.

let objects = require('common/objects');
let permissions = require('common/permissions');

let folder = objects.find('/agorum/roi/Files/Beispielordner');

let entries = permissions.getPermissions(folder.UUID);

let readerNames = [];
entries.forEach(function (entry) {
  if (entry.permission === 'read') {
    let reader = objects.tryFind(entry.granteeId);
    if (reader) {
      readerNames.push(reader.name);
    }
  }
});
// z. B. [ 'demo' ]

getPermissions zeigt eine Regel auch dann, wenn am Objekt keine Basis-ACL gesetzt ist und deshalb keine ACL entsteht.

Berechtigung entfernen

Das Beispiel entfernt das Leserecht des Benutzers demo wieder. Entfernt wird nur eine direkt gesetzte Berechtigung, keine vererbte. Alle direkt gesetzten Berechtigungen auf einmal entfernt removeAllPermissions(folder.UUID).

let objects = require('common/objects');
let permissions = require('common/permissions');

let folder = objects.find('/agorum/roi/Files/Beispielordner');
let demo = objects.find('user:demo');

permissions.removePermission(folder.UUID, {
  granteeId: demo.UUID,
  permission: 'read'
});

Basis-ACL entfernen

Rufen Sie setBaseAcl ohne ACL-Namen auf, entfernt das System nur die Metadaten sys_pm_base und sys_pm_defined vom Objekt. Die Metadaten der Stufen, zum Beispiel sys_pm_read, bleiben bestehen. Die Folgen:

• getPermissions liefert danach eine leere Liste, die Regeln werden aber weiter vererbt.
• Die ACL und die Scope-ACLs bleiben am Objekt, werden aber nicht mehr gepflegt.
• Hat ein übergeordnetes Objekt eine Basis-ACL, erbt das Objekt sie und bleibt weiter verwaltet.

Rufen Sie deshalb zuerst removeAllPermissions und gegebenenfalls removeBlock auf.

let objects = require('common/objects');
let permissions = require('common/permissions');

let folder = objects.find('/agorum/roi/Files/Beispielordner');

permissions.removeAllPermissions(folder.UUID);
permissions.setBaseAcl(folder.UUID);

Vererbung unterbrechen

Mit einem Blocker unterbrechen Sie die Vererbung einer Berechtigung an einem Objekt. setBlock sperrt die Vererbung für eine Berechtigung, getBlocks liefert die gesperrten Berechtigungen als Liste und removeBlock hebt die Sperre wieder auf.

let objects = require('common/objects');
let permissions = require('common/permissions');

let folder = objects.find('/agorum/roi/Files/Beispielordner');

permissions.setBlock(folder.UUID, 'read');
let blocks = permissions.getBlocks(folder.UUID);
// [ 'read' ]

permissions.removeBlock(folder.UUID, 'read');