Zugriffsrechte (ACL) im Detail

Diese Seite erklärt, wie ioBroker entscheidet, ob ein Benutzer etwas lesen, auflisten, schreiben, anlegen oder löschen darf: bei Objekten, bei Zuständen und bei Dateien. Wer nur einen eingeschränkten Benutzer anlegen möchte, findet die Schritt-für-Schritt-Anleitung unter Zugriffsverwaltung mit Benutzern und Gruppen. Hier geht es um das Modell dahinter.

Das Wichtigste in Kürze

• Jeder Zugriff muss zwei Schranken passieren: die Gruppenrechte des Benutzers und die ACL am einzelnen Eintrag. Sperrt eine davon, passiert nichts.
• Die ACL funktioniert wie die Dateirechte unter Linux: Besitzer, Besitzergruppe, Jeder, jeweils mit lesen und schreiben.
• Die Zahl ist hexadezimal, nicht oktal wie unter Linux: 0x664, nicht 0664.
• Es gilt immer genau eine der drei Rollen, und zwar die erste, die passt.
• Objekt, Zustand und Datei haben getrennte Rechte, auch wenn Objekt und Zustand dieselbe ID tragen.
• Der Benutzer admin und die Mitglieder der Administratorgruppe sind von der ACL an Objekten, Dateien und Zuständen ausgenommen und dürfen alles.

Zwei Schranken

Gruppenrechte und ACL beantworten zwei verschiedene Fragen:

Ein Benutzer, dessen Gruppe Zustände schreiben darf, scheitert trotzdem an einem Datenpunkt, dessen ACL ihm nur Lesen erlaubt. Umgekehrt nützt eine offene ACL nichts, wenn die Gruppe das Schreiben von Zuständen gar nicht erlaubt.

Anfrage: Benutzer "fred" will alias.0.Licht schalten
   │
   ├─ 1. Gruppenrechte: darf fred Zustände schreiben?      nein → abgelehnt
   │                                                          ja ↓
   └─ 2. ACL von alias.0.Licht: welche Rolle hat fred,
         und erlaubt die Ziffer dieser Rolle das Schreiben?  nein → abgelehnt
                                                               ja → erlaubt

Was geschützt wird

?> Ein Datenpunkt hat damit zwei ACL-Zahlen: eine für das Objekt und eine für den Zustand. Wer nur schalten können soll, braucht Schreibrechte am Zustand. Schreibrechte am Objekt erlauben dagegen, den Datenpunkt umzubauen.

Wer fragt: Benutzer, Gruppen und Sonderfälle

Benutzer und Gruppen

Benutzer sind Objekte mit der ID system.user.<name>, Gruppen haben die ID system.group.<name>. Diese Benutzer gibt es nur innerhalb von ioBroker, mit den Benutzern des Betriebssystems haben sie nichts zu tun.

Wer in einer Gruppe ist, steht in der Gruppe, in common.members, nicht beim Benutzer:

{
  "_id": "system.group.user",
  "type": "group",
  "common": {
    "name": "User",
    "members": ["system.user.fred"],
    "acl": { "...": "..." }
  }
}

Mehrere Gruppen

Ein Benutzer kann in beliebig vielen Gruppen sein. Seine Gruppenrechte sind dann die Vereinigung aller Gruppen: jedes einzelne Recht ist erlaubt, sobald eine seiner Gruppen es erlaubt. Eine Gruppe kann einem Benutzer also nichts wegnehmen, was eine andere ihm gibt.

Ein Benutzer in keiner Gruppe darf nichts.

Sonderfälle: admin und die Administratorgruppe

Die Administratorgruppe darf damit immer alles, genau wie der Benutzer admin. Ihre Rechte lassen sich im Admin auch nicht bearbeiten. Einschränken lässt sich deshalb nur ein Benutzer, der nicht in dieser Gruppe ist.

!> Wer einen Benutzer in die Administratorgruppe aufnimmt, gibt ihm Zugriff auf alles, unabhängig von jeder ACL. Für eingeschränkte Zugänge eine eigene Gruppe anlegen.

Wer ist „der Benutzer" bei einem Zugriff?

• Angemeldet im Admin oder in einer Visualisierung: der angemeldete Benutzer.
• Anmeldung ausgeschaltet: der Benutzer, der in der Instanz als Standardbenutzer eingetragen ist. Bei admin und web ist das ab Werk admin, also ohne jede Einschränkung.
• Adapter und Skripte intern: Ein Zugriff ohne Benutzerangabe gilt als admin.

!> ACLs schützen damit vor allem, was angemeldete Benutzer über die Web-Oberflächen tun. Solange die Anmeldung ausgeschaltet ist, greift keine der hier beschriebenen Einschränkungen.

Schranke 1: Gruppenrechte

Die Operationen

Die Rechte einer Gruppe sind in Blöcke geteilt: Objekte, Zustände, Benutzer, Dateien und Andere. Die ersten vier kennen dieselben Operationen:

Der Block Andere hat drei eigene Rechte:

!> Shell-Ausführung bedeutet Zugriff auf das Betriebssystem, mit den Rechten des Benutzers, unter dem ioBroker läuft. Und sendTo erlaubt Nachrichten an jede Instanz und jeden Host, über die sich viele Adapter fernsteuern lassen. Beide Rechte gehören nur Personen, denen man auch den Server anvertrauen würde.

Welche Aktion welches Recht braucht

So prüfen die Web-Schnittstellen (Admin, web, socketio und weitere):

Voreinstellung der beiden Gruppen

Ein Mitglied der Gruppe Benutzer kann damit alles sehen und schalten, aber nichts umbauen, keine Dateien ändern und keine Aufträge an Adapter schicken.

Schranke 2: die ACL am einzelnen Eintrag

So sieht sie aus

An einem Objekt, das zugleich Zustand ist:

{
  "_id": "alias.0.Licht",
  "type": "state",
  "common": { "...": "..." },
  "acl": {
    "owner": "system.user.admin",
    "ownerGroup": "system.group.administrator",
    "object": 1636,
    "state": 1636
  }
}

An einer Datei im Dateispeicher:

{
  "acl": {
    "owner": "system.user.admin",
    "ownerGroup": "system.group.administrator",
    "permissions": 1636
  }
}

1636 ist die dezimale Schreibweise von 0x664. Die Datenbank speichert die Zahl dezimal, der Admin zeigt sie hexadezimal als 664.

Die Zahl lesen: wie Linux, aber hexadezimal

Die ACL-Zahl hat drei Stellen, eine je Rolle, in dieser Reihenfolge:

Jede Stelle ist die Summe ihrer Rechte, genau wie unter Linux:

Das Ausführen-Bit (1) gibt es, ioBroker wertet es aber nicht aus. Eine 7 bedeutet also dasselbe wie eine 6.

Übliche Werte:

!> In Skripten und in JSON nie 664 schreiben. Das ist dezimal 664, also 0x298: der Besitzer dürfte nur schreiben und nicht lesen, Gruppe und Jeder bekämen Bits, die gar nichts bedeuten. Richtig ist 0x664 oder dezimal 1636. Auch Linux-Gewohnheit hilft hier nicht: das oktale 0o664 ist dezimal 436, also 0x1b4.

Welche Stelle gilt: immer genau eine Rolle

ioBroker sucht die Rolle des Benutzers in dieser Reihenfolge und nimmt die erste, die passt:

1. Ist der Benutzer der Besitzer? Dann gilt nur die erste Stelle.
2. Sonst: Ist er in der Besitzergruppe, egal ob in seiner ersten oder in einer weiteren Gruppe? Dann gilt nur die zweite Stelle.
3. Sonst gilt die dritte Stelle.

Die Stellen werden nicht zusammengezählt. Wie unter Linux kann der Besitzer deshalb weniger dürfen als seine Gruppe: Bei 0x464 darf der Besitzer nur lesen, obwohl die Besitzergruppe schreiben darf. Die zweite Stelle gilt für ihn nicht, weil schon die erste passt.

Wenn nichts eingetragen ist

Wie eine Anfrage geprüft wird

Die folgenden Tabellen gelten für alle Benutzer außer den oben genannten Sonderfällen. „ACL" meint das Bit der Rolle, die der Benutzer an diesem Eintrag hat.

Objekte

?> Eine Liste enthält nur Objekte, die der Benutzer auch lesen darf. Was seine ACL nicht lesen lässt, taucht im Objektbaum gar nicht erst auf. Löschen hat kein eigenes ACL-Bit: wer ein Objekt schreiben darf, darf es mit dem passenden Gruppenrecht auch löschen.

Zustände

Wird ein Zugriff abgelehnt, schreibt die Instanz eine Warnung ins Log, die mit Permission error for user beginnt und den Benutzer, die ID und den Befehl nennt.

Dateien

Eine neue Datei gehört dem Benutzer, der sie schreibt. Ihre Rechte kommen aus der Standard-ACL.

!> Nach dem aktuellen Stand des js-controllers scheitert das Löschen von Dateien für alle Benutzer außerhalb der Administratorgruppe, auch wenn Gruppenrecht und Datei-ACL es erlauben. Wer Dateien löschen können soll, muss derzeit in die Administratorgruppe.

Benutzer und Gruppen

Die Objekte system.user.* und system.group.* sind gewöhnliche Objekte mit einer zusätzlichen Schranke. Für sie müssen drei Dinge erlauben:

1. das Gruppenrecht im Block Benutzer, also lesen, auflisten, schreiben, erstellen oder löschen,
2. das passende Gruppenrecht im Block Objekte,
3. die ACL des Benutzer- oder Gruppenobjekts.

Die beiden mitgelieferten Gruppen stehen auf 0x644 und gehören admin. Ohne Administratorrechte kann sie deshalb niemand ändern, selbst mit allen Häkchen im Block Benutzer.

Voreinstellungen für neue Einträge

Was neue Objekte, Zustände und Dateien bekommen, steht in den Systemeinstellungen unter Standard ACL. Gespeichert wird es in system.config, im Feld common.defaultNewAcl:

"defaultNewAcl": {
  "owner": "system.user.admin",
  "ownerGroup": "system.group.administrator",
  "object": 1636,
  "state": 1636,
  "file": 1636
}

Ist dort nichts eingetragen, gilt genau das: Besitzer admin, Gruppe administrator, 0x664 für Objekte, Zustände und Dateien.

Wird die Standard-ACL geändert, bekommen auch bestehende Objekte die neuen Werte, allerdings nur die, die noch gar keine ACL haben. Objekte mit eigener ACL bleiben, wie sie sind.

!> Objekte, die ein Adapter selbst anlegt, gehören ihm. Legt er sie bei einem Update neu an, stehen auch die Rechte wieder so, wie der Adapter sie vorsieht. Wo eine Einschränkung dauerhaft halten soll, ist ein Alias der verlässlichere Weg: er gehört Ihnen, und der Adapter fasst ihn nicht an.

Rechte setzen

Im Admin

Gruppenrechte: Reiter Benutzer, Bleistift an der Gruppe, Reiter Berechtigungen.

ACL eines Objekts: Im Reiter Objekte den Expertenmodus einschalten. Dann erscheint eine Spalte mit der ACL-Zahl, ein Klick darauf öffnet den Dialog:

Oben stehen Besitzer-Nutzer und Besitzer-Gruppe, darunter die Rechte getrennt nach Objekt und Zustand, jeweils für Besitzer, Gruppe und Jeder. Der Schalter Auf das Objekt und seine Unterobjekte anwenden überträgt die Einstellung auf den ganzen Teilbaum.

Auf der Kommandozeile

Alle Zahlen werden hexadezimal gelesen, 644 bedeutet also 0x644. Benutzer und Gruppen dürfen ohne Präfix angegeben werden, fred wird zu system.user.fred.

# Objekt- und Zustandsrechte: erst die Objektzahl, dann optional die Zustandszahl
iobroker object chmod 644 664 alias.0.*

# nur die Objektrechte
iobroker object chmod 644 system.adapter.*

# Besitzer und Besitzergruppe von Objekten
iobroker object chown fred user alias.0.*

# Dateirechte: erstes Pfadstück ist der Namensraum, etwa vis-2.0
iobroker chmod 644 /vis-2.0/main/*
iobroker chown fred user /vis-2.0/main/*

# Benutzer und Gruppen
iobroker user add fred --ingroup user
iobroker user passwd fred
iobroker group adduser user fred
iobroker group deluser user fred
iobroker user get fred
iobroker group get user

Weitere Befehle stehen unter Kommandozeile.

Im Skript

Im JavaScript-Adapter mit extendObject. Die Zahlen als Hex-Literal schreiben:

extendObject('0_userdata.0.Gast.Licht', {
    acl: {
        owner: 'system.user.admin',
        ownerGroup: 'system.group.gast',
        object: 0x644,
        state: 0x664,
    },
});

Linux und ioBroker im Vergleich

Beispiel: ein Gast, der nur seine eigenen Geräte schaltet

Ziel: Ein Benutzer gast sieht alles, schaltet aber nur die Datenpunkte unter 0_userdata.0.Gast.

1. Gruppe und Benutzer anlegen

iobroker group add gast
iobroker user add gast --ingroup gast

Im Admin, an der Gruppe gast, die Rechte setzen:

2. Die eigenen Datenpunkte der Gruppe geben

iobroker object chown admin gast 0_userdata.0.Gast.*
iobroker object chmod 644 664 0_userdata.0.Gast.*

3. Was jetzt passiert

Soll gast die übrigen Datenpunkte gar nicht erst sehen, bekommen diese als dritte Stelle eine 0, etwa 0x660. Dann fehlen sie in seinem Objektbaum.

4. Anmelden — in der Authentifizierung des Web-Adapters die Anmeldung einschalten, sonst arbeitet jeder als admin. Dann mit gast anmelden und prüfen, ob wirklich nur das geht, was gehen soll.

Fehlersuche

!> Vor größeren Umstellungen ein Backup anlegen. Wer sich mit zu strengen Rechten selbst aussperrt, kommt nur noch über die Kommandozeile wieder hinein: iobroker object chmod und iobroker object chown arbeiten immer mit Administratorrechten.