• Deutsch

      • Sicherheit und Audit

      Voraussetzung

      Bevor Sie diese Seite lesen, stellen Sie bitte sicher, dass Sie NocoBase CLI gemäß dem Schnellstart KI-Builder installiert und initialisiert haben.

      Wenn Benutzer NocoBase über die NocoBase CLI durch einen AI Agent steuern, sollten Authentifizierung, Berechtigungssteuerung und Audit besondere Aufmerksamkeit erhalten, damit klare Operationsgrenzen sichergestellt sind und der gesamte Vorgang nachvollziehbar bleibt.

      Authentifizierung

      Für die Verbindung eines AI Agent mit NocoBase stehen im Wesentlichen zwei Authentifizierungsverfahren zur Verfügung:

      • API-Key-Authentifizierung: Mit dem Plugin API keys wird ein API Key erzeugt, in der CLI-Umgebung konfiguriert und für nachfolgende Anfragen direkt zur API-Nutzung verwendet
      • OAuth-Authentifizierung: Über den Browser wird einmalig eine OAuth-Anmeldung durchgeführt; danach erfolgt der API-Zugriff im Namen des aktuellen Benutzers

      Beide Verfahren lassen sich in Verbindung mit dem nb-Befehl nutzen. Die Unterschiede liegen in Identitätsherkunft, Anwendungsszenario und Risikosteuerungsstrategie.

      API-Key-Authentifizierung

      API Keys eignen sich vor allem für automatisierte, skriptbasierte und langfristig laufende Aufgaben, zum Beispiel:

      • Lassen Sie einen AI Agent regelmäßig Daten synchronisieren
      • In der Entwicklungsumgebung häufiges Aufrufen von nb api
      • Ausführung einer eindeutigen, stabilen Aufbauaufgabe mit fester Rolle

      Der grundlegende Ablauf:

      1. Aktivieren Sie in NocoBase das API-keys-Plugin und erstellen Sie einen API Key
      2. Weisen Sie diesem API Key eine dedizierte Rolle zu, statt direkt die vollen Berechtigungen von root oder eines Administrators zu vergeben
      3. Speichern Sie API-Adresse und Token mit nb env add in der CLI-Umgebung

      Beispiel:

      nb env add local \
  --scope project \
  --api-base-url http://localhost:13000/api \
  --auth-type token \
  --access-token <your-api-key>

      Nach Abschluss der Konfiguration kann der AI Agent über diese Umgebung API-Aufrufe durchführen:

      nb api resource list --env local --resource users

      Dieses Verfahren ist stabil, eignet sich für Automatisierung und der Benutzer muss sich nicht jedes Mal erneut anmelden. Solange das Token nicht abgelaufen ist, kann jeder, der es besitzt, dauerhaft mit den Berechtigungen der zugewiesenen Rolle auf das System zugreifen. Daher ist besonders zu beachten:

      • Token nur an dedizierte Rollen binden
      • Nur in den notwendigen CLI-Umgebungen speichern
      • Regelmäßig rotieren – „läuft nie ab" sollte nicht die Standardeinstellung sein
      • Bei Verdacht auf Kompromittierung sofort löschen und neu erzeugen

      Weitere allgemeine Hinweise finden Sie im NocoBase-Sicherheitsleitfaden.

      OAuth-Authentifizierung

      OAuth eignet sich vor allem für Aufgaben, die im Namen des aktuell angemeldeten Benutzers ausgeführt werden sollen, zum Beispiel:

      • Die KI nimmt für den aktuellen Administrator eine einmalige Konfigurationsanpassung vor
      • Operationen sollen einem klar identifizierten angemeldeten Benutzer zugeordnet sein
      • Hochberechtigte Token sollen nicht langfristig gespeichert werden

      Der grundlegende Ablauf:

      1. Fügen Sie zunächst die CLI-Umgebung hinzu und wählen Sie als Authentifizierungstyp oauth
      2. Führen Sie nb env auth aus
      3. Der Browser öffnet die Authentifizierungsseite – Anmelden und Authentifizierung abschließen
      4. Die CLI speichert die Authentifizierungsinformationen; nachfolgende nb api-Anfragen greifen dann im Namen des aktuellen Benutzers auf NocoBase zu
      5. Falls der Benutzer mehrere Rollen hat, lässt sich die Rolle über --role festlegen

      Beispiel:

      nb env add local \
  --scope project \
  --api-base-url http://localhost:13000/api \
  --auth-type oauth

nb env auth local

      nb env auth startet den Browser-Anmeldevorgang. Nach Erfolg speichert die CLI die Authentifizierungsinformationen in der aktuellen Umgebungskonfiguration, und der AI Agent kann anschließend weiterhin nb api aufrufen.

      Die Gültigkeitsdauer von OAuth-Access-Tokens und OAuth-Refresh-Tokens folgt der systemweiten Konfiguration der Token-Richtlinie.

      • Die Gültigkeitsdauer von OAuth-Access-Tokens entspricht der Gültigkeitsdauer der System-Tokens; der Standardwert ist 1 Tag
      • Die Gültigkeitsdauer von OAuth-Refresh-Tokens entspricht der Gültigkeitsdauer der Systemsitzung; der Standardwert ist 7 Tage

      Die CLI nutzt, sobald das Access-Token abzulaufen droht, vorrangig das Refresh-Token, um die Sitzung automatisch zu erneuern. Ist das Refresh-Token bereits abgelaufen, nicht verfügbar oder gibt der Server keines zurück, müssen Sie nb env auth erneut ausführen. Wenn Sie die Token-Richtlinie ändern, müssen Sie das System neu starten, damit die Änderung im OAuth-Dienst wirksam wird.

      Charakteristisch für OAuth ist, dass Anfragen typischerweise im Rolle-Kontext des aktuell angemeldeten Benutzers ausgeführt werden und sich Audit-Aufzeichnungen leichter konkreten Akteuren zuordnen lassen. Dieses Verfahren eignet sich besser für Operationen mit menschlicher Beteiligung und erforderlicher Identitätsbestätigung.

      Empfohlene Praxis

      Wir empfehlen folgende Auswahlprinzipien:

      • Entwicklungs-, Test- und Automatisierungsaufgaben: bevorzugt API Keys verwenden, aber unbedingt an dedizierte Rollen binden
      • Produktionsumgebung, Aufgaben mit menschlicher Beteiligung, starker Identitätszuschreibung: bevorzugt OAuth verwenden
      • Risikoreiche Operationen: Auch wenn technisch ein Token möglich wäre, sollten Sie auf OAuth umsteigen und die Authentifizierung von einem Benutzer mit entsprechenden Berechtigungen durchführen lassen

      Falls keine eindeutigen Anforderungen vorliegen, können Sie sich an folgenden Standardprinzipien orientieren:

      • Standardmäßig OAuth verwenden
      • Nur dann API Keys verwenden, wenn ausdrücklich Automatisierung, unbeaufsichtigter Betrieb oder Stapelverarbeitung erforderlich sind

      Berechtigungssteuerung

      Ein AI Agent verfügt selbst über keine „zusätzlichen Berechtigungen". Was er tun kann, hängt vollständig von der aktuell genutzten Identität und Rolle ab.

      Anders gesagt:

      • Beim Zugriff per API Key wird die Berechtigungsgrenze durch die diesem Token zugewiesene Rolle bestimmt
      • Beim Zugriff per OAuth wird die Berechtigungsgrenze durch den aktuell angemeldeten Benutzer und dessen aktuelle Rolle bestimmt

      Die KI umgeht das ACL-System von NocoBase nicht. Wenn eine Rolle keine Berechtigung für eine bestimmte Datentabelle, ein Feld, eine Seite oder eine Plugin-Konfiguration hat, kann der AI Agent den entsprechenden Befehl auch dann nicht erfolgreich ausführen, wenn er ihn kennt.

      Rollen und Berechtigungsstrategie

      Es wird empfohlen, für den AI Agent eine eigene Rolle einzurichten, statt eine bestehende Administratorrolle wiederzuverwenden.

      Diese Rolle benötigt in der Regel nur Berechtigungen in folgenden Bereichen:

      • Welche Datentabellen darf sie bearbeiten
      • Welche Aktionen darf sie ausführen, etwa Anzeigen, Erstellen, Aktualisieren, Löschen
      • Darf sie auf bestimmte Seiten oder Menüs zugreifen
      • Darf sie Hochrisikobereiche wie Systemeinstellungen, Plugin-Verwaltung oder Berechtigungskonfiguration betreten

      Beispielsweise können Sie eine Rolle ai_builder_editor anlegen, die nur Folgendes darf:

      • CRM-bezogene Datentabellen verwalten
      • Bestimmte Seiten bearbeiten
      • Einen Teil der Workflows auslösen
      • Keine Änderung der Rollenberechtigungen
      • Keine Aktivierung, Deaktivierung oder Installation von Plugins
      • Kein Löschen kritischer Datentabellen

      Wenn die KI bei der Konfiguration von Berechtigungen helfen soll, können Sie dies in Verbindung mit der Berechtigungskonfiguration tun. Es wird jedoch empfohlen, die Berechtigungsgrenzen weiterhin zunächst manuell festzulegen.

      Prinzip der minimalen Berechtigung

      Das Prinzip der minimalen Berechtigung ist im KI-Builder-Szenario besonders wichtig. Sie können wie folgt vorgehen:

      1. Erstellen Sie zunächst eine dedizierte Rolle für die KI
      2. Gewähren Sie ihr anfangs nur Leseberechtigungen
      3. Ergänzen Sie schrittweise die für die Aufgabe notwendigen Berechtigungen wie Erstellen oder Bearbeiten
      4. Behalten Sie für risikoreiche Operationen wie Löschen, Berechtigungsänderungen oder Plugin-Verwaltung die manuelle Kontrolle

      Beispiele:

      • Eine KI für die Inhaltspflege benötigt nur Anzeige- und Erstellungsberechtigungen für die Zieldatentabelle
      • Eine KI für den Seitenaufbau benötigt nur die zugehörigen Seiten- und UI-Konfigurationsberechtigungen
      • Einer KI zur Datenmodellierung gewähren Sie Strukturänderungen nur in der Testumgebung, nicht direkt in der Produktion

      Es wird nicht empfohlen, dem AI Agent direkt Rollen wie root, admin oder Rollen mit globalen Systemkonfigurationsrechten zuzuweisen. Auch wenn dies die Bereitstellung vereinfacht, vergrößert es die Angriffsfläche der Berechtigungen erheblich.

      Protokolle

      Im KI-Builder-Szenario dienen Protokolle der Operationsnachverfolgung und der Problemlokalisierung.

      Im Fokus stehen zwei Protokollarten:

      • Anfrageprotokolle: erfassen Pfad, Methode, Statuscode, Dauer und Quelle der API-Anfragen
      • Audit-Protokolle: erfassen den Akteur, das Operationsobjekt, das Ergebnis und zugehörige Metadaten kritischer Ressourcenoperationen

      Beim Aufruf über nb api fügt die CLI automatisch den Header x-request-source: cli hinzu, sodass der Server erkennen kann, dass die Anfrage von der CLI stammt.

      Anfrageprotokolle

      Anfrageprotokolle dienen dazu, Informationen zu API-Aufrufen festzuhalten, einschließlich Anfragepfad, Antwortstatus, Dauer und Herkunftskennzeichnung.

      Die Protokolldateien befinden sich üblicherweise unter:

      storage/logs/<appName>/request_YYYY-MM-DD.log

      Im Szenario eines nb api-Aufrufs enthält das Anfrageprotokoll Folgendes:

      • req.header.x-request-source

      Daran lassen sich CLI-Anfragen von gewöhnlichen Browseranfragen unterscheiden.

      Erläuterungen zu Verzeichnis und Feldern der Anfrageprotokolle finden Sie unter NocoBase-Serverprotokolle.

      Audit-Protokolle

      Audit-Protokolle erfassen Akteure, Zielressourcen, Ausführungsergebnisse und zugehörige Anfrageinformationen kritischer Operationen.

      Für Operationen, die in den Auditbereich aufgenommen wurden, werden im Protokoll folgende Felder erfasst:

      • resource
      • action
      • userId
      • roleName
      • status
      • metadata.request.headers.x-request-source

      Wenn die KI beispielsweise über die CLI collections:apply, fields:apply oder andere mit aktiviertem Audit versehene Schreiboperationen aufruft, wird im Audit-Protokoll x-request-source: cli erfasst, sodass sich Operationen aus der Oberfläche und über die CLI klar unterscheiden lassen.

      Eine ausführliche Beschreibung der Audit-Protokolle finden Sie unter Audit-Protokoll.

      Sicherheitsempfehlungen

      Im Folgenden finden Sie einige Praxisempfehlungen, die besser zum KI-Builder-Szenario passen:

      • Weisen Sie dem AI Agent nicht direkt Rollen wie root, admin oder Rollen mit globaler Systemkonfiguration zu
      • Erstellen Sie eine dedizierte Rolle für den AI Agent und gliedern Sie die Berechtigungsgrenzen aufgabenspezifisch
      • Rotieren Sie API Keys regelmäßig und vermeiden Sie die langfristige Wiederverwendung desselben hochberechtigten Tokens
      • Validieren Sie Änderungen an Datenmodell, Seitenstruktur und Workflows zunächst in der Testumgebung, bevor Sie sie in die Produktion übertragen
      • Aktivieren und prüfen Sie regelmäßig Anfrage- und Audit-Protokolle, um die Nachvollziehbarkeit kritischer Operationen sicherzustellen
      • Bei Hochrisikooperationen wie Datenlöschung, Berechtigungsänderung, Aktivierung/Deaktivierung von Plugins oder Anpassung von Systemkonfigurationen wird eine manuelle Bestätigung vor der Ausführung empfohlen
      • Wenn die KI langfristig laufen muss, teilen Sie sie vorzugsweise auf mehrere Umgebungen mit niedrigeren Berechtigungen auf, statt sich auf eine zentrale Hochberechtigungsumgebung zu verlassen