Authentifizierung

Edge Connector Security

Der Edge Connector muss sich bei der nara-Plattform authentifizieren, bevor er Tool-Aufrufe empfangen und ausführen kann. Die Authentifizierung stellt die Identität des Connectors fest, verknüpft ihn mit deiner Organisation und autorisiert ihn für den Zugriff auf den Platform Server. Diese Seite behandelt die verfügbaren Authentifizierungsmodi, den Token-Lebenszyklus und Best Practices zur Sicherheit.

Authentifizierungsmodi

Der Edge Connector unterstützt drei Authentifizierungsmethoden, die jeweils für verschiedene Deployment-Szenarien geeignet sind.

Browser-OAuth

Browser-OAuth ist die interaktive Authentifizierungsmethode für den Desktop-Modus. Sie öffnet deinen Standardbrowser, leitet dich zur nara-Anmeldeseite weiter und gibt nach erfolgreicher Autorisierung einen JWT-Token zurück.

edge-connector auth --browser

So funktioniert es:

1. Die CLI kontaktiert die Plattform und erhält einen Autorisierungscode und eine Browser-URL.

2. Die CLI öffnet die Browser-URL. Du meldest dich mit deinem Konto an und genehmigst den Zugriff des Edge Connectors auf deine Organisation.

3. Nach der Genehmigung ruft die CLI automatisch den Session-Token ab.

4. Der Token wird validiert (Ablauf, Organisationszugehörigkeit) und im konfigurierten Token-Pfad gespeichert.

5. Das Standard-Bundle deiner Organisation wird automatisch synchronisiert.

Dieser Modus ist der Standard, wenn du die Edge Connector Runtime auf einem Desktop-Rechner startest. Wenn beim Start kein Token gefunden wird, initiiert die Runtime automatisch den Browser-OAuth-Flow.

Deployment-Anmeldedaten

Deployment-Anmeldedaten sind für Headless-, Server- und Cloud-Deployments gedacht, bei denen kein Browser verfügbar ist. Statt interaktivem OAuth nutzt der Edge Connector ein DEPLOYMENT_ID- und DEPLOYMENT_SECRET-Paar als Umgebungsvariablen.

export DEPLOYMENT_ID="dep_abc123"
export DEPLOYMENT_SECRET="sec_xyz789"

So funktioniert es:

• Die Runtime erkennt beim Start das Vorhandensein beider Umgebungsvariablen DEPLOYMENT_ID und DEPLOYMENT_SECRET.
• Statt einen JWT-Token zu laden, übergibt die Runtime diese Anmeldedaten direkt an den Platform-Client während des WebSocket-Handshakes.
• Der Platform Server validiert die Anmeldedaten gegen den Deployment-Eintrag und stellt die Verbindung her.
• Es wird keine Token-Datei erstellt oder benötigt.

Dieser Modus wird automatisch verwendet, wenn beide Umgebungsvariablen gesetzt sind. Er hat Vorrang vor tokenbasierter Authentifizierung.

Tipp

Deployment-Anmeldedaten werden im nara Admin-Panel unter Deployments erstellt und verwaltet. Jedes Deployment hat ein eindeutiges ID-und-Secret-Paar.

Token-Datei

Die Token-Datei-Authentifizierung ist nützlich für automatisierte Setups, bei denen du den Token vor dem Start der Runtime vorab bereitstellst.

edge-connector auth --token /path/to/auth-token.json

Token-Dateiformat:

Die Token-Datei ist eine JSON-Datei mit dem JWT und einem Zeitstempel:

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "savedAt": "2025-01-15T10:30:00.000Z"
}

Du kannst auch einen rohen JWT-String direkt angeben:

edge-connector auth --token "eyJhbGciOiJSUzI1NiIs..."

Die CLI löst die Eingabe auf: Wenn es ein gültiger Dateipfad ist, liest sie die Datei und extrahiert das token-Feld. Wenn es ein roher String ist, wird er direkt als JWT verwendet.

Token-Validierung

Jeder Token wird validiert, bevor er gespeichert oder verwendet wird. Die Validierung prüft:

Prüfung	Beschreibung
Format	Der Token muss ein gültiger Zugriffstoken sein
Ablauf	Der Token muss noch gültig sein und darf nicht abgelaufen sein
Organisation	Der Token muss zu einer Organisation gehören, die dein Konto mit diesem Connector verwenden darf

Wenn eine Prüfung fehlschlägt, gibt die CLI eine spezifische Fehlermeldung aus und beendet sich, ohne zu speichern.

Token-Speicherung

Tokens werden als JSON-Dateien im lokalen Dateisystem gespeichert. Der Speicherort wird durch folgende Priorität bestimmt:

1. Die Umgebungsvariable AUTH_TOKEN_PATH, falls gesetzt.

2. Das Feld authTokenPath in config.json.

3. Der Standardpfad: ./auth-token.json (relativ zum Installationsverzeichnis).

Die Token-Datei wird mit restriktiven Berechtigungen erstellt (0600 — nur Lesen/Schreiben für den Besitzer) und das enthaltende Verzeichnis wird auf 0700 gesetzt (nur Besitzer). So wird sichergestellt, dass der Token nicht von anderen Benutzern auf dem System gelesen werden kann.

Token-Aktualisierung und Ablauf

JWT-Tokens haben eine von der nara-Plattform gesetzte Ablaufzeit. Wenn ein Token abläuft:

• Desktop-Modus: Die Runtime erkennt den abgelaufenen Token bei der Validierung und initiiert automatisch einen neuen Browser-OAuth-Flow. Wenn das System Tray aktiv ist, zeigt es einen “ausstehend”-Status während der erneuten Authentifizierung an.
• Server-Modus mit Deployment-Anmeldedaten: Nicht zutreffend — Deployment-Anmeldedaten laufen nicht auf die gleiche Weise ab wie JWT-Tokens. Die Anmeldedaten bleiben gültig, solange das Deployment existiert.
• Token-Datei-Modus: Du musst die Token-Datei manuell durch einen neuen Token ersetzen. Die Runtime kann sich nicht verbinden, wenn der Token abgelaufen ist.

Die Runtime validiert den Token beim Start und gibt eine Warnung aus, wenn der Token bald abläuft.

Desktop-Auth-Flow

Der Desktop-Authentifizierungs-Flow ist ein zweistufiger Prozess, der es einer Headless-CLI ermöglicht, sich über einen Browser auf derselben Maschine zu authentifizieren.

CLI                    Platform                   Browser
 |                        |                          |
 |-- POST /start -------->|                          |
 |<-- code + url ---------|                          |
 |                        |                          |
 |-- open browser --------|------------------------->|
 |                        |<-- user logs in ---------|
 |                        |<-- user approves --------|
 |                        |                          |
 |-- GET /session/token ->|                          |
 |<-- JWT token ----------|                          |
 |                        |                          |
 |-- save token           |                          |

Umgebungsvariablen-Overrides

Authentifizierungsbezogene Umgebungsvariablen überschreiben Config-Datei-Werte:

Variable	Beschreibung
AUTH_TOKEN_PATH	Pfad zur Token-Datei überschreiben
DEPLOYMENT_ID	Deployment-Identifier für Cloud-/Server-Modus
DEPLOYMENT_SECRET	Deployment-Secret für Cloud-/Server-Modus
DEPLOYMENT_CREDENTIALS_PATH	Pfad zu einer Datei mit Deployment-Anmeldedaten

Best Practices zur Sicherheit

• Committe niemals Token-Dateien oder Deployment-Secrets in die Versionskontrolle. Füge auth-token.json und Anmeldedaten-Dateien zu deiner .gitignore hinzu. - Verwende für Produktions-Deployments Umgebungsvariablen oder Secret-Manager statt Token-Dateien. - Rotiere Deployment-Anmeldedaten regelmäßig über das Admin-Panel. - Die Token-Datei sollte nur vom Benutzer lesbar sein, der den Edge Connector ausführt (chmod 600 auth-token.json). - Injiziere bei Container-Nutzung die Anmeldedaten über Umgebungsvariablen oder gemountete Secrets, nicht eingebaut ins Image.