Berechtigungen und Scopes

Opfield verwendet ausdrückliche Scopes. Ein Scope hat eine Fähigkeitsbasis und kann ein Ressourcensuffix enthalten.

docker:containers:view
docker:containers:view:<node-id>/<resource-id>
databases:view:<database-id>
nodes:details:<node-id>

Die Fähigkeitsbasis beschreibt die erlaubte Aktion. Ein Ressourcensuffix schränkt diese Aktion auf die Identität eines Nodes oder einer Ressource ein. Opfield wertet an der Grenze der Backend-Operation die authentifizierte Identität, die wirksamen Gruppen- und direkten Berechtigungen, die Zuständigkeit für die Ressource, den aktuellen Produktzustand und den Leistungsumfang des Tarifs aus. Sichtbarkeit in der Navigation und deaktivierte Bedienelemente helfen Benutzern, ihren Zugriff zu verstehen, sind aber keine Autorisierung.

Berechtigungen beantworten zwei getrennte Fragen: welche Aktion erlaubt ist und welche Ressource im Geltungsbereich liegt. Ein Benutzer kann möglicherweise einen Container ansehen, ohne sensible Host-Details zu sehen, oder eine Route verwalten, ohne jede Route auf ihrem Ingress Node zu verwalten. Bevorzugen Sie die kleinste Berechtigung, die den tatsächlichen Ablauf unterstützt, statt breiten Zugriff zu vergeben, um einen fehlenden Bildschirm zu vermeiden.

Gestaltungsregeln

1. Vergeben Sie normalen Zugriff über Gruppen; reservieren Sie direkte Zuweisungen an Benutzer für Ausnahmen.
2. Bevorzugen Sie ressourcenbezogene Berechtigungen gegenüber einem ganzen Node oder Produktbereich.
3. Trennen Sie das Ansehen von Änderungen, dem Anzeigen von Secrets, Exporten, Mounts und destruktiven Aktionen.
4. Behandeln Sie API-Tokens und OAuth-Freigaben als delegierte Befugnis, nicht als alternative Administratoren.
5. Testen Sie den resultierenden Ablauf aus Benutzersicht, einschließlich der Sichtbarkeit in der Navigation und der Ablehnung direkter API-Aufrufe.

Beginnen Sie mit der Aufgabe, die die Identität erfüllen muss. Listen Sie die Leseaktionen auf, die nötig sind, um das Ziel zu finden und zu prüfen, die Änderungsaktionen, die nötig sind, um es zu ändern, und alle gesondert geschützten Daten oder destruktiven Aktionen. Beschränken Sie dann jede Berechtigung auf genau die Ressource, den Node oder den Ordner, in den die Arbeit gehört. Gruppenmitgliedschaften sind normalerweise leichter zu prüfen und zu entziehen als viele direkte Benutzerberechtigungen.

Vergeben Sie keinen globalen Verwaltungs-Scope, nur weil der Ablauf mehrere Ressourcentypen berührt. Ein Veröffentlichungsablauf benötigt möglicherweise eingeschränkten Zugriff auf ein Pages-Projekt, eine Domain, ein Zertifikat, eine Route und den Status eines Build Workers, aber weder allgemeine Node-Administration noch den Export privater Schlüssel. Testen Sie den vollständigen Ablauf vor dem Produktionseinsatz mit der vorgesehenen Identität ohne Administratorrechte.

Scope-Ebenen und Sichtbarkeit

Globale Scopes gelten im gesamten erlaubten Produktbereich. Node-bezogene Berechtigungen beschränken Operationen auf Ressourcen auf einem bestimmten verwalteten Node, wenn der Ressourcenvertrag diesen Scope unterstützt. Ressourcenbezogene Berechtigungen bezeichnen eine dauerhafte Opfield-Ressource. Ordner können unterstützte Ressourcen gruppieren und an der Zugriffsgestaltung mitwirken, aber das Verschieben einer Ressource in einen Ordner ändert weder ihre Laufzeitzuständigkeit noch ihren Netzwerkpfad.

Jeder Aktions-Scope schließt das Ansehen derselben Ressourcen ein: proxy:edit:<route-id> zeigt diese Route, und docker:containers:manage:<node-id> zeigt die Container auf diesem Node. Erstellungs-Scopes sind die Ausnahme: Sie schließen überhaupt keine Ansicht ein, ob sie breit gefasst oder auf einen Ordner oder Node beschränkt sind. Siehe Implizierter Lesezugriff.

Apps sind mit apps:view auf der App oder auf einer ihrer Umgebungen sichtbar. Ohne diesen Scope sieht ein Benutzer eine App trotzdem, wenn er eines ihrer Mitglieder – einen Container, ein Deployment, ein Compose-Projekt, eine Datenbank, einen Speicher, eine Route oder eine Pages-Website – über eigene Berechtigungen auf der Ressource, auf dem Ordner der Umgebung oder auf dem Ordner der App sehen kann. Er sieht dann nur die Umgebungen, die diese Mitglieder enthalten, und nur diese Mitglieder, und Übersicht, Aktivität und Vorfälle sind auf sie beschränkt. Variablen, erlaubte Nodes, Wartung, Übernahme in eine andere Umgebung und jede App-Aktion benötigen weiterhin ihre App-Scopes.

Sichtbarkeit von Ressourcen und Sichtbarkeit von Hosts sind bewusst getrennt. Ein Benutzer kann einen zugewiesenen Workload betreiben, ohne fremdes Host-Inventar kennenzulernen. Suche, Navigation, REST, MCP-Erkennung, Echtzeit-Abonnements und direkte Ressourcenanfragen müssen alle dieselben wirksamen Zugriffsregeln anwenden. Ein ausgeblendeter Navigationseintrag beweist keine Ablehnung; prüfen Sie auch eine direkte Anfrage.

Zugriff auf einen Ordner beschränken

Eine Ordnerberechtigung beschränkt einen Benutzer, eine Gruppe, ein API-Token oder eine OAuth-Freigabe auf die Ressourcen innerhalb eines Ordners und seiner Unterordner. Das eignet sich für ein Projektteam, das nur seine eigenen Ressourcen sehen und betreiben soll, zum Beispiel alles, was zu MyProject gehört.

1. Erstellen Sie in jedem Bereich, den das Team nutzt, einen Ordner MyProject, zum Beispiel unter Routes, Docker-Containern und Databases. Jeder Ressourcentyp hat seinen eigenen Ordnerbaum, daher deckt ein Ordner unter Routes keine Container ab. Siehe Ordnerunterstützung nach Ressourcentyp.
2. Verschieben Sie die bestehenden Ressourcen des Projekts in diese Ordner. Das Verschieben einer Ressource erfordert den Ordnerverwaltungs-Scope des Bereichs und Bearbeitungszugriff auf die Ressource.
3. Wählen Sie im Gruppeneditor oder in den zusätzlichen Berechtigungen des Benutzers die Scopes aus, die das Team benötigt, öffnen Sie die Einschränkung jedes Scopes und wählen Sie den Ordner MyProject. Die gespeicherte Berechtigung hat die Form <scope>:folder/<folder-id>.

Ziel	Auf den Ordner beschränkte Scopes
Container und Deployments des Projekts sehen und betreiben	docker:containers:view, docker:containers:manage; fügen Sie docker:containers:environment, docker:containers:secrets oder docker:containers:console nur bei Bedarf hinzu
Neue Container und Deployments im Ordner erstellen, einschließlich des Beziehens ihrer Images	docker:containers:create
Die Routen des Projekts verwalten	proxy:view, proxy:edit, proxy:create
Die Datenbanken des Projekts abfragen	databases:view, databases:query:read

Was der Benutzer sieht:

• Jede Ressource im Ordner und in seinen Unterordnern, einschließlich Ressourcen, die später darin erstellt oder dorthin verschoben werden. Opfield löst Ordnerberechtigungen bei jeder Anfrage auf, und geöffnete Seiten übernehmen neu sichtbare Ressourcen ohne erneute Anmeldung.
• Sonst nichts: Listen zeigen nur die berechtigten Ressourcen, ein berechtigter Ordner, der noch leer ist, zeigt eine leere Liste, und direkte Anfragen nach anderen Ressourcen werden abgelehnt. Eine Ressource, die aus dem Ordner verschoben wird, ist nicht mehr sichtbar, sofern der Benutzer keine separate Berechtigung dafür hat.
• Erstellungsdialoge bieten nur die Ordner an, in denen der Benutzer erstellen darf. No folder wird ausgeblendet, wenn der Benutzer nicht auf oberster Ebene erstellen darf, und der einzige erlaubte Ordner ist vorausgewählt. Übergeben Sie den Ordner über die API oder MCP als folderId; das Erstellen an anderer Stelle liefert 403. Wo eine Ressource auf einem Node läuft, listet der Dialog nur Nodes auf, auf denen der Benutzer bereitstellen darf, ohne Node-Administration zu gewähren.
• Ein Erstellungs-Scope allein zeigt den Ordner als Ziel, aber nichts von seinem Inhalt. Vergeben Sie zusätzlich einen Lese-Scope auf den Ordner, wenn das Team sehen soll, was bereits darin liegt.
• Container und Deployments, die aus einer Git-Quelle erstellt werden, landen im gewählten Ordner, auch wenn der erste Build sie erst später erstellt. Während einer auf seinen ersten Build wartet, wird er in diesem Ordner aufgeführt und kann mit Move to folder… oder per Ziehen verschoben werden; der erste Build erstellt ihn dann in dem Ordner, in dem er sich zu diesem Zeitpunkt befindet. Siehe Ordnerplatzierung gebauter Workloads.
• Ein abgelehntes Erstellen nennt die Ordner und Nodes, in denen der Benutzer stattdessen erstellen darf, zum Beispiel Missing docker:containers:create at the root (no folder). Your docker:containers:create access is limited to folder 'MyProject' (<id>): pass folderId for one of them. Docker-Erstellungen liefern diese Meldung in der Konsole und der REST API; bei anderen Ressourcentypen fügen Werkzeugfehler von MCP und AI Workspace dieselbe Liste von Ordnern und Nodes hinzu.

Settings > Authentication > Identity provisioning > Auto-assign permissions for created resources ist standardmäßig aktiviert. Die Einstellung fügt den zusätzlichen Berechtigungen des Erstellers Berechtigungen für jede neue Ressource hinzu: immer das Ansehen der neuen Ressource und weitere ressourcenbezogene Scopes nur dann, wenn der Ersteller sie bereits breit oder auf dem Zielordner bzw. -Node besitzt. Ein Benutzer mit nur einem Erstellungs-Scope sieht daher genau die Ressourcen, die er erstellt hat. Ein auf einen Ordner beschränkter Ersteller behält daher denselben Zugriff, wenn die Ressource später aus dem Ordner verschoben wird, gewinnt aber nichts Neues hinzu: Ansehen und Erstellen in einem Ordner werden nicht zu Konsolen- oder Secret-Zugriff. Das Deaktivieren der Einstellung betrifft nur neue Ressourcen; bestehende Berechtigungen bleiben erhalten und können unter Assign permissions geändert werden.

API-Tokens und OAuth-Freigaben akzeptieren dieselben Ordnereinschränkungen. Ihre Ordner werden zuerst aufgelöst, und das Ergebnis wird dann durch den eigenen Zugriff des Eigentümers begrenzt, sodass ein Token nie mehr sieht als sein Eigentümer; siehe Tokens und OAuth-Freigaben einschränken.

Sehen, was eine Identität erreichen kann

GET /api/auth/me/access liefert den Zugriff des Aufrufers gruppiert nach Produktbereich: ob er breit oder beschränkt ist, die berechtigten Ordner mit ihren Pfaden, die Nodes, Konten und einzelnen Ressourcen mit den jeweils erlaubten Aktionen sowie wo der Aufrufer erstellen darf (create.atRoot, create.folders, create.nodes). Der Endpunkt funktioniert mit einer Sitzung, einem API-Token oder einem OAuth-Token und meldet ein Token oder eine OAuth-Freigabe als durch den aktuellen Zugriff seines Eigentümers begrenzt. ID, Name, E-Mail-Adresse und Gruppe des Benutzers sind nur bei einer Browsersitzung und im AI Workspace enthalten, niemals bei einem Token. MCP-Clients und der AI Workspace erhalten dieselbe Zusammenfassung über das Werkzeug get_my_access, und MCP stellt sie zusätzlich als Ressource opfield://access bereit; siehe Herausfinden, worauf der Aufrufer zugreifen kann.

Auf Ordner beschränkter Zugriff ist für Agenten und Automatisierung normal. Eine Liste liefert nur, was der Aufrufer sehen darf, daher ist eine leere Liste auf oberster Ebene keine Ablehnung. Wenn Sie eine auf Ordner beschränkte Identität testen, lesen Sie zuerst ihre Zugriffszusammenfassung und erstellen Sie dann mit folderId in einem der aufgeführten Ordner.

Git-Zugriff auf Repositories beschränken

Scopes der Git-Integration können auf ein verbundenes Konto und darunter auf GitLab-Gruppen und -Projekte oder GitHub-Owner und -Repositories beschränkt werden. Eine Berechtigung auf eine GitLab-Gruppe deckt ihre Untergruppen und jedes Projekt darunter ab; eine Berechtigung auf einen GitHub-Owner deckt jedes Repository dieser Organisation oder dieses Benutzers ab. Markieren Sie im Gruppeneditor, in den zusätzlichen Berechtigungen eines Benutzers, im Formular für API-Tokens und in der OAuth- und MCP-Zustimmung einen Connector, um alle seine Repositories abzudecken, oder öffnen Sie unter dem Connector Add groups or projects… (GitLab) bzw. Add owners or repositories… (GitHub) und suchen Sie nach engeren Zielen. Berechtigungen speichern stabile IDs des Anbieters, daher ändert das Umbenennen oder Verschieben einer Gruppe oder eines Repositorys sie nicht.

Damit ein Team aus einem Projekt bauen kann, vergeben Sie integrations:gitlab:use auf dieses Projekt neben den eigenen Berechtigungen des Workloads: use auf das Projekt genügt, um eine Docker- oder Pages-Build-Quelle zu konfigurieren. Behalten Sie diese Berechtigung bei: Manuelle Builds prüfen sie erneut, und automatische Builds einer in diesem Release gespeicherten Quelle pausieren, wenn das Konto, das sie gespeichert hat, use verliert. API-Tokens und OAuth-Freigaben tragen dieselben Einschränkungen und erreichen nie ein Repository, das ihr Eigentümer in diesem Moment nicht erreichen kann. Das Format der Qualifizierer finden Sie unter Einschränkungen der Git-Integration, und was jede Operation prüft, unter Repository-Zugriff einschränken.

Workloads betreiben, ohne sie zu übernehmen

Ressourcenbezogene Docker-Berechtigungen funktionieren bei Containern, die Opfield erkannt, aber nicht erstellt hat. Sie können ein Team einen Dienst neu starten und seine Logs lesen lassen, ohne den gesamten Host oder die Konfiguration der Anwendung an Opfield zu übergeben.

Ziel	Berechtigung	Hinweise
Logs, Statistiken und Prozesse eines eigenständigen Containers lesen	docker:containers:view:<node-id>/<resource-id>	Es gibt keinen separaten Log-Scope; view deckt sie ab
Einen eigenständigen Container starten, stoppen, neu starten oder beenden und seine Logs lesen	docker:containers:manage:<node-id>/<resource-id>	manage schließt view auf denselben Container ein. Es erlaubt auch Beenden und Neuerstellen; einen Scope nur für den Neustart gibt es nicht
Eine Shell in diesem Container öffnen	zusätzlich docker:containers:console:<node-id>/<resource-id>	Konsolenzugriff ist immer eine separate Berechtigung
Die zusammengefassten Logs und das Monitoring eines externen Compose-Projekts lesen	docker:compose:view:<node-id>/<project-id>	Funktioniert vor der Übernahme und in jedem Tarif
Ein Compose-Projekt starten, stoppen oder neu starten	docker:compose:manage:<node-id>/<project-id>, nachdem das Projekt übernommen wurde	Externe Projekte sind bis zur Übernahme schreibgeschützt; Lebenszyklusaktionen gelten für das gesamte Projekt, nicht für einzelne Compose-Container
Denselben Zugriff auf eine Gruppe von Ressourcen anwenden	dieselben Scopes mit folder/<folder-id>	Deckt unterstützte Ressourcen im Docker-Ordner und seinen Unterordnern ab

Ein eigenständiger Container ist jeder Container ohne Projekt-Labels von Docker Compose, einschließlich eines mit docker run gestarteten. Opfield gibt ihm eine stabile Ressourcenidentität, die Neuerstellungen und Updates über Opfield übersteht. Wird der Container außerhalb von Opfield entfernt und erneut gestartet, erfasst Opfield eine neue Ressource und entzieht die Berechtigungen auf die alte Identität. Siehe Container, die Opfield nicht erstellt hat.

Ein externes Compose-Projekt behält seine Identität, solange Opfield es beobachtet. Verschwindet das Projekt vom Node, zum Beispiel nach docker compose down, entfernt Opfield es aus dem Inventar, sofern das Projekt nicht in einem Docker-Ordner liegt; taucht es wieder auf, erhält es eine neue Identität, und Berechtigungen auf die alte Projektidentität passen nicht mehr. Legen Sie externe Projekte mit projektbezogenen Berechtigungen in einen Docker-Ordner oder vergeben Sie den Zugriff über den Ordner.

Wichtige Trennungen

• Das Bearbeiten von Containern schließt das Bearbeiten von Mounts nicht ein.
• Datenbankzugriff schließt das Anzeigen von Zugangsdaten nicht ein.
• Die Nutzung von Inference schließt den Zugriff auf AI Workspace nicht ein.
• Das Ansehen einer Ressource schließt das Ansehen der Details ihres Host-Nodes nicht ein.
• Das Bearbeiten von Routen schließt den Export privater Zertifikatsschlüssel nicht ein.

Andere sensible Operationen folgen demselben Prinzip. Konsolen- oder Dateizugriff ist getrennt vom gewöhnlichen Ansehen eines Workloads. Der Archivexport ist getrennt vom Ansehen von Dateien oder der Ressourcenkonfiguration. Das Ändern eines Secrets schließt sein Anzeigen nicht ein, und nur schreibbare Werte werden ersetzt statt abgerufen. OAuth-Zustimmung und die Erkennung von MCP-Werkzeugen fügen keine Scopes hinzu, die der zugehörige Benutzer nicht besitzt.

AI Workspace und Remote-MCP bleiben innerhalb der normalen Opfield-Autorisierung. Zugriff auf AI Workspace und die Nutzung von Opfield Inference sind getrennte Fähigkeiten. Remote-MCP erfordert eine eigene OAuth-Ressource und mcp:use; Browsersitzungen, gewöhnliche gw_-API-Tokens, Logging-Tokens, Inference-Tokens oder OAuth-Tokens, die für eine andere Ressource ausgestellt wurden, sind keine austauschbaren MCP-Zugangsdaten.

Programmatische Identitäten

Verwenden Sie getrennte Zugangsdaten für interaktive Administration, CI, Monitoring und Werkzeuge von Drittanbietern. Ein API-Token handelt mit delegierter Befugnis seines Opfield-Benutzers. Ein OAuth-Client fügt einen ausdrücklichen Lebenszyklus für Weiterleitung und Zustimmung hinzu. Remote-MCP verwendet OAuth und stellt nur Werkzeuge bereit, die mit der aktuellen Identität und dem aktuellen Produktzustand vereinbar sind. Ein eigenes gwi_-Token gehört zur Datenebene von Opfield Inference und kann nicht als normale Zugangsberechtigung für die Opfield API verwendet werden.

Erstellen Sie Zugangsdaten für die Automatisierung mit einem Eigentümer, einem Zweck, einer erwarteten Rotation und einem bekannten abhängigen System. Speichern Sie Secrets einmal in einem Secret-Manager, niemals in Repository-URLs, im Befehlsverlauf, auf Screenshots oder in Logs. Testen Sie eine erlaubte und eine abgelehnte Aktion. Geht ein Token verloren, erstellen Sie einen Ersatz und widerrufen Sie den alten Wert; maskierte Secrets können über die Oberfläche nicht wiederhergestellt werden.

Widerruf

Sitzungs-, API-, MCP- und geschützte WebSocket-Operationen prüfen den Zugriff erneut. Der Widerruf einer Gruppe, eines Tokens oder einer Ressourcenberechtigung muss neue privilegierte Aktionen stoppen und bei Bedarf geschützte Datenströme beenden. Eine zuvor geladene Seite oder ein bereits erkanntes Werkzeug behält nach dem Widerruf keine Befugnis.

Wenn sich die Aufgaben eines Benutzers ändern, prüfen Sie Gruppenmitgliedschaften, direkte Berechtigungen, aktive Sitzungen, API-Tokens, OAuth-Freigaben und Abhängigkeiten der Automatisierung gemeinsam. Das Sperren eines Benutzers stoppt neue Nutzung, ohne die Zuordnung zu löschen. Das Löschen eines Benutzers bewahrt historische Audit-Einträge, und das Wiederherstellen eines gelöschten Eintrags reaktiviert ihn nicht stillschweigend. Das Entfernen des letzten Administrators wird abgelehnt.

Das Löschen einer Ressource – eines Nodes, einer Route, einer Domain, eines Zertifikats, einer CA, einer Access List, einer Vorlage, einer Gruppe, eines Ordners, eines Connectors, eines Pages-Projekts, einer Datenbank, eines Speichers, einer Logging-Umgebung, eines Deployments, eines Compose-Projekts, einer App oder einer anderen Ressource – entfernt jede Berechtigung, die sie benennt, von Benutzern, Gruppen, API-Tokens sowie OAuth- und MCP-Freigaben, sodass eine spätere Ressource mit demselben Namen sie niemals erbt. Berechtigungen auf Ressourcen, die vor 2.11 gelöscht wurden, werden beim Start und stündlich entfernt.

Erstellen Sie bei der Rotation von Zugangsdaten zuerst den Ersatz, aktualisieren Sie das abhängige System, prüfen Sie die erfolgreiche Nutzung und widerrufen Sie dann die alten Zugangsdaten. Widerrufen Sie nach einer vermuteten Offenlegung zuerst, sofern es betrieblich sicher ist, prüfen Sie die Audit-Aktivität und Request-IDs, machen Sie zugehörige Sitzungen separat ungültig und rotieren Sie jedes nachgelagerte Secret, das offengelegt worden sein könnte.

Prüfung und Fehlerdiagnose

Testen Sie Berechtigungen mit der Identität, die sie verwenden wird, nicht mit einem Administratorkonto. Bestätigen Sie die erwartete Sichtbarkeit in Navigation und Suche, lesen Sie die Zielressource, führen Sie eine erlaubte Operation aus und versuchen Sie eine eindeutig außerhalb des Geltungsbereichs liegende Operation. Testen Sie bei Automatisierung außerdem einen Validierungsfehler und die Nachverfolgung asynchroner Tasks.

Deuten Sie häufige Fehler genau: 401 weist auf fehlende oder ungültige Authentifizierung hin; 403 bedeutet meist einen fehlenden Scope oder Leistungsumfang; 404 kann sowohl die Sichtbarkeit einer Ressource als auch ihr Fehlen widerspiegeln; 409 weist auf einen Konflikt mit Lebenszyklus, Kontingent oder aktuellem Zustand hin; und 422 weist auf ungültige Eingaben hin. Lösen Sie einen Konflikt mit Leistungsumfang oder Lebenszyklus nicht durch Erweitern von Berechtigungen.

Abläufe zur Umsetzung finden Sie unter Scopes, Tokens und OAuth.