Scopes, API-Tokens, OAuth und MCP

Unter Scope-Referenz finden Sie jede Berechtigung, ihre Beschreibung, unterstützte Einschränkungen und die Delegierung an Tokens.

Programmatischer Zugriff sollte leichter zu widerrufen und enger gefasst sein als die Sitzung eines menschlichen Administrators. Der Verantwortliche der Automatisierung legt den benötigten Ablauf fest, der Ressourcenverantwortliche gibt ihre Reichweite frei, und der Sicherheitsverantwortliche prüft Lebensdauer und Speicherung der Zugangsdaten. Erfolg bedeutet, dass die Integration ihre vorgesehene Aktion ausführen kann, anderswo abgewiesen wird und rotiert werden kann, ohne unbeteiligte Systeme zu unterbrechen.

Benutzer verwalten API-Tokens unter Profile > Authorizations > API Tokens. Secrets werden einmal angezeigt. Speichern Sie sie in einem Secret-Manager, vergeben Sie die minimalen Scopes und widerrufen Sie ungenutzte Tokens.

OAuth-Clients delegieren Benutzerbefugnisse mit ausdrücklichen Redirect-URIs und Zustimmung. Remote-MCP verwendet dasselbe Ressourcen- und Scope-Modell wie REST und die Konsole; es ist keine privilegierte Hintertür.

Verwenden Sie getrennte Zugangsdaten für CI, Monitoring und interaktive Werkzeuge. Vermeiden Sie langlebige Administrator-Tokens. Beschränken Sie Automatisierung auf genau die Nodes, Routen, Workloads, Datenbanken oder Pages-Projekte, die ihr gehören.

Gewöhnliche gw_-API-Zugangsdaten und OAuth-Zugangsdaten gelangen nicht in die Datenebene von Opfield Inference. Inference verwendet eigene gwi_-Benutzertokens.

Protokollieren Sie Erstellung, Verwendung und Widerruf von Tokens im Audit. Rotieren Sie nach einer vermuteten Offenlegung sofort und prüfen Sie aktive Sitzungen separat.

Den Typ der Zugangsdaten wählen

Zugangsdaten	Verwendung
Sitzung	Interaktiver Zugriff auf die Operations Console
API-Token	Direkte Automatisierung, die einem Opfield-Benutzer gehört
OAuth-Client	Delegierte Benutzerautorisierung und Anwendungen von Drittanbietern
Remote-MCP-OAuth	Werkzeug-Clients, die über die MCP-Oberfläche von Opfield handeln
Inference-Token	Anfragen an die separate Datenebene von Opfield Inference

Ersetzen Sie einen Typ nicht durch einen anderen, nur weil er leichter zu kopieren ist. Der Typ der Zugangsdaten bestimmt Zustimmung, Widerruf, Scope-Auswertung, Audit-Zweck und die Familie der Endpunkte, auf die er zugreifen kann.

Ein Token mit minimalen Rechten erstellen

Ermitteln Sie die genauen Operationen und Ressourcen, die der Automatisierung gehören.
Erstellen Sie einen eigenen Benutzer oder eine eigene Dienstidentität, wenn die Zuordnung getrennt sein soll.
Vergeben Sie die minimalen globalen und ressourcenbezogenen Scopes.
Erstellen Sie das Token und erfassen Sie das Secret einmal.
Speichern Sie es in einem Secret-Manager und speisen Sie es zur Laufzeit ein.
Testen Sie eine erlaubte und eine abgewiesene Anfrage.
Halten Sie Eigentümer, Zweck, erwarteten Ablauf bzw. erwartete Rotation und abhängiges System fest.

Betten Sie Tokens nicht in Repository-URLs, den Befehlsverlauf, Screenshots oder Logs ein. Ein maskierter Wert in der Oberfläche kann später nicht wiederhergestellt werden; erstellen Sie einen Ersatz und widerrufen Sie das alte Token, wenn das Secret verloren geht.

Was Tokens können und was nicht

API-Tokens und OAuth-Freigaben für die Opfield API oder MCP können jeden Berechtigungs-Scope enthalten außer einer kurzen Liste nur für Benutzer: die Scopes für AI Workspace und AI-Sandboxes (ai:workspace:use, feat:ai:configure, ai:skills:manage und ai:sandbox:*), mcp:use, admin:users:impersonate und integrations:gitlab:sandbox:clone. Programmatischer Zugriff kann daher Nodes und ihre Konfiguration, Benutzer und Gruppen, Opfield-Einstellungen, Integrations- und Hosting-Connectoren, Hosting-VMs, Relay-Operationen, Updates, die Inference-Administration und die persönlichen gwi_-Inference-Schlüssel des Eigentümers verwalten. Jeder delegierte Scope bleibt durch die aktuellen Berechtigungen des Eigentümers begrenzt.

Manche Aktionen bleiben an eine interaktive Browsersitzung gebunden:

das Erstellen von API-Tokens und OAuth-Autorisierungen sowie die OAuth-Zustimmung selbst;
der Chat von AI Workspace und AI-Sandboxes;
das Starten einer Impersonation;
die Anmeldung und das Ändern der eigenen Anmeldemethoden, MFA, Passkeys oder Sitzungen des Eigentümers; ein Token, das es versucht, liefert SELF_SIGN_IN_PROGRAMMATIC;
die Verwaltung persönlicher GitLab-Zugangsdaten.

Da Tokens jetzt administrative Scopes enthalten können, behandeln Sie ein Token mit Administrator-Scopes wie ein Administratorkonto: Geben Sie ihm einen Eigentümer, einen Ablauf und nach Möglichkeit einen engen Ressourcen-Scope.

Opfield 2.11 hat mehrere Scopes umbenannt. Die Token-Erstellung, OAuth-Parameter scope und Bearbeitungen von OAuth-Autorisierungen akzeptieren die alten Namen noch für zwei Releases und speichern die neuen; bestehende Tokens und Freigaben wurden beim Update umgewandelt. Ein neues Token oder eine neue OAuth-Anfrage für einen Scope wie integrations:github:manage erhält außerdem die Scopes, die das Update dafür hinzugefügt hat (hier repo:read), sofern Sie sie besitzen; der Zustimmungsbildschirm zeigt sie, und Sie können sie abwählen. Scopes, die eine manuelle Freigabe erfordern, etwa repo:write oder pki:ca:export, werden nie auf diese Weise hinzugefügt. Siehe Außer Dienst gestellte Scope-Namen.

Tokens und OAuth-Freigaben einschränken

Ein Token oder eine OAuth-Freigabe kann wie die Berechtigungen eines Benutzers auf Ordner, Nodes, App-Umgebungen oder einzelne Ressourcen beschränkt werden. Eine Ordnereinschränkung umfasst den Ordner, seine Unterordner und Ressourcen, die später darin erstellt oder dorthin verschoben werden. Siehe Zugriff auf einen Ordner beschränken.

API-Tokens: Der Token-Dialog unter Profile > Authorizations > API Tokens zeigt den Zugriff des Tokens als Liste. Add Access fügt eine Zeile hinzu. Wählen Sie unter Resources eine Role, Where sie gilt (Everywhere, In a project folder, In an app environment oder Specific resources) und was sie umfasst (Covers); wählen Sie unter Git repositories einen Connector, die Repositories und die Zugriffsstufe. Der Dialog bietet nur an, was Sie selbst vergeben können.
Scope-Auswahl: Review N scopes unten im Token-Dialog und im OAuth- und MCP-Zustimmungsbildschirm öffnet die Scopes selbst. Jede Abschnittsüberschrift zeigt, wohin die Scopes des Abschnitts reichen: Everywhere, ein Ort oder N places. Klicken Sie darauf, um aus den Ordnern, Apps und Umgebungen zu wählen, die diese Art von Ressource enthalten. Die Scopes eines Abschnitts folgen ihm; Only this scope… gibt einem Scope eine eigene Einschränkung. Ein Scope, den Sie nur für einige Ressourcen besitzen, zeigt No resources selected, bis Sie diese auswählen.
OAuth- und MCP-Zustimmung: Der Zustimmungsbildschirm zeigt, was der Client anfordert, als Zugriffszeilen. Scopes mit hohem Risiko bleiben außerhalb der Freigabe, bis Sie sie unter Review N scopes freigeben. Um Scopes und Einschränkungen einer bestehenden Autorisierung später zu ändern, öffnen Sie sie unter Profile > Authorizations > OAuth Applications, bearbeiten Sie Scopes und klicken Sie auf Save Scopes.
Git-Integrationen: Die Scope-Auswahl beschränkt Git-Scopes auf einen Connector, eine GitLab-Gruppe oder ein GitLab-Projekt bzw. einen GitHub-Owner oder ein GitHub-Repository, mit Add groups or projects… bzw. Add owners or repositories… unter jedem Connector. Ein solches Token wird bei jeder Repository-Operation gegen seine eigene Einschränkung und gegen Ihren aktuellen Git-Zugriff geprüft, sodass es ein Repository nicht mehr erreicht, sobald Sie den Zugriff darauf verlieren. Siehe Einschränkungen der Git-Integration.

Opfield löst zuerst die eigenen Ordner- und Node-Einschränkungen eines Tokens auf und begrenzt das Ergebnis dann durch Ihren aktuellen Zugriff, sodass ein Token nie mehr sieht als Sie. Eine Erstellungsberechtigung zählt beim Delegieren nie als Leseberechtigung. Fordert ein Client einen breiten Scope an, den Sie nur für einige Ressourcen besitzen, engt Opfield die Freigabe auf diese Ressourcen ein.

OAuth und MCP

Registrieren Sie genaue Redirect-URIs und lehnen Sie Wildcard-Weiterleitungsverhalten ab. Prüfen Sie die angeforderten Scopes bei der Zustimmung und trennen Sie Entwicklungs- von Produktions-Clients. Die Zustimmung lässt Scopes mit hohem Risiko standardmäßig unmarkiert, sodass sie ausdrücklich ausgewählt werden müssen – zum Beispiel admin:system, admin:users, admin:groups, settings:opfield:edit, nodes:manage, proxy:raw:write, proxy:unrestricted, proxy:templates:manage, pki:ca:export, System-Zugangsdaten von Connectoren (integrations:*:use), integrations:ssh:use, kostenpflichtige oder destruktive Hosting-Aktionen, storage:credentials:reveal, storage:iam, databases:backups:restore und feat:ai:use. Remote-MCP-Werkzeuge verwenden dieselben Autorisierungsprüfungen und dieselbe Ressourcensichtbarkeit wie REST und die Konsole; die Erkennung eines Werkzeugs gewährt keine Berechtigung, es auszuführen.

Behandeln Sie Autorisierungsfehler unterschiedlich:

401: fehlende, abgelaufene oder ungültige Authentifizierung;
403: der authentifizierten Identität fehlt der erforderliche Scope oder Leistungsumfang;
409: der aktuelle Ressourcenzustand oder ein Kontingent steht im Konflikt mit der Operation;
422: die Validierung der Anfrage ist fehlgeschlagen.

Abgelaufene OAuth-Autorisierungscodes und -Tokens sowie OAuth-Clients, die 90 Tage lang keine Freigabe hatten, werden von der Housekeeping-Kategorie Expired OAuth Grants entfernt; ein Refresh-Token wird bis zu seinem Ablauf aufbewahrt, damit seine Wiederverwendung weiterhin erkannt wird. Siehe Housekeeping und Aufbewahrung.

Rotation und Reaktion auf Vorfälle

Erstellen Sie 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, machen Sie zugehörige Sitzungen separat ungültig und rotieren Sie jedes nachgelagerte Secret, das offengelegt worden sein könnte.

Gestaltung und Zuständigkeit von Scopes

Beginnen Sie mit der Operation, nicht mit einem Rollennamen. Listen Sie die genauen Lese- und Änderungsaufrufe auf, die die Integration benötigt, und binden Sie Ressourcen-Scopes dann an die kleinste stabile Zuständigkeitsgrenze: einen Ordner, Node, eine Route, einen Workload, eine Datenbank oder ein Pages-Projekt. Fügen Sie einen globalen Scope nur hinzu, wenn der Ablauf wirklich alle Ressourcen dieses Typs berührt. Trennen Sie Berechtigungen für Ansehen, Anzeigen von Zugangsdaten, Export, Konsole, Mounts, Secrets und Lebenszyklus; gewöhnlicher Lesezugriff darf keinen Zugriff auf Zugangsdaten oder hostsensible Operationen einschließen.

Alle Zugangsdaten benötigen einen menschlichen Eigentümer, einen maschinellen Verbraucher, einen Zweck, eine Umgebung und eine Bedingung für ihre Entfernung. Ein Token, das von CI verwendet wird, sollte nicht auch für die Terminalsitzung eines Operators verwendet werden. Produktions- und Nicht-Produktions-OAuth-Clients sollten unterschiedliche Client-IDs, Redirect-URIs, Secrets und Zustimmungseinträge haben. Ändert sich die Zuständigkeit, übertragen oder ersetzen Sie die Zugangsdaten, statt sie am Konto eines ausgeschiedenen Benutzers zu belassen.

Betriebliche Prüfung

Bevor Sie Automatisierung in der Produktion aktivieren:

Rufen Sie mit den neuen Zugangsdaten einen harmlosen Lese-Endpunkt auf.
Führen Sie eine beabsichtigte Änderung an einer Wegwerf-Ressource aus.
Weisen Sie nach, dass eine Ressource außerhalb des Geltungsbereichs ausgeblendet oder abgewiesen wird.
Bestätigen Sie, dass die Audit-Zuordnung den erwarteten Benutzer oder OAuth-Client identifiziert.
Prüfen Sie, dass Token-Werte, Authorization-Header und Callback-Parameter in Logs geschwärzt sind.
Widerrufen Sie die Zugangsdaten und weisen Sie nach, dass der Verbraucher sicher fehlschlägt (fail closed).
Installieren Sie den Ersatz und dokumentieren Sie die getestete Reihenfolge der Rotation.

Der Widerruf eines API-Tokens beendet nicht automatisch Browsersitzungen, OAuth-Freigaben, Inference-Tokens oder Zugangsdaten, die bei externen Anbietern gespeichert sind. Erfassen Sie bei einem Vorfall jede Familie von Zugangsdaten separat.