Authentifizierung & Tokens

Security Admin Only

Authentifizierungsmethoden im Überblick

nara unterstützt mehrere Authentifizierungsmethoden, je nachdem wie du auf die Plattform zugreifst:

Web-Login

Die primäre Authentifizierungsmethode für Web-Nutzer. nara unterstützt SSO, Social Login, E-Mail/Passwort und Multi-Faktor-Authentifizierung. Wenn du dich über die nara-Webanwendung anmeldest, übernimmt die Plattform den gesamten Authentifizierungsablauf.

JWT Tokens

JSON Web Tokens werden vom Edge Connector und API-Clients zur Authentifizierung gegenüber der Plattform verwendet. JWTs enthalten Claims über die Identität des Benutzers und die Organisationszugehörigkeit und werden bei jeder Anfrage validiert.

Server Tokens

Langlebige Tokens, die über die Settings-Seite für programmatischen API-Zugang erstellt werden. Server Tokens sind an deine Organisation gebunden und können in Automatisierungsskripten, CI/CD-Pipelines und Drittanbieter-Integrationen verwendet werden.

Server Tokens erstellen

Server Tokens ermöglichen programmatischen Zugriff auf die nara-API ohne interaktiven Login. Um einen Token zu erstellen:

1. Navigiere zu Settings > API & Security.

2. Klicke auf Generate Token.

3. Gib dem Token einen Namen, der seinen Zweck beschreibt (z. B. “CI Pipeline”, “Monitoring Script”, “External Integration”).

4. Klicke auf Create. Der Token wird einmalig angezeigt — kopiere ihn sofort und speichere ihn sicher.

5. Der Token erscheint in deiner Token-Liste mit Name, Erstellungsdatum und Zeitstempel der letzten Verwendung.

Achtung

Der Token-Wert wird nur einmalig bei der Erstellung angezeigt. Wenn du ihn verlierst, musst du einen neuen Token erstellen. Die Plattform speichert den Klartext-Token nicht.

Token-Scoping

Server Tokens sind auf deine Organisation beschränkt:

• Organisationsgebunden — jeder Token ist an die Organisation gebunden, in der er erstellt wurde. Er kann nicht auf Ressourcen anderer Organisationen zugreifen.
• Voller API-Zugang — Server Tokens gewähren Zugriff auf alle API-Endpunkte deiner Organisation, abhängig von deiner Lizenzstufe.
• Kein Benutzerkontext — Server Tokens handeln im Namen der Organisation, nicht eines bestimmten Benutzers. Aktionen mit einem Server Token werden für das Auditing mit dem Token-Namen protokolliert.

Tokens in API-Anfragen verwenden

Füge den Server Token im Authorization-Header deiner HTTP-Anfragen ein:

curl -X GET https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer <YOUR_SERVER_TOKEN>" \
  -H "Content-Type: application/json"

Alle API-Endpunkte akzeptieren Bearer-Token-Authentifizierung. Der Token wird bei jeder Anfrage validiert — wenn der Token widerrufen oder die Organisation deaktiviert wurde, wird die Anfrage mit einer 401 Unauthorized-Antwort abgelehnt.

Beispiel: ausführbare funktionale Agents programmatisch auflisten

curl -X GET https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer nara_tk_abc123..." \
  -H "Content-Type: application/json"

Beispiel: Eine funktionale Agent-Ausführung auslösen

curl -X POST https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer nara_tk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "summarizeTicket",
    "args": {
      "ticketNumber": "1234"
    }
  }'

Best Practices für Token-Sicherheit

Regelmäßig rotieren

Erstelle regelmäßig neue Tokens und widerrufe alte. Das begrenzt das Zeitfenster bei einer Kompromittierung. Lege einen Rotationsplan fest (z. B. alle 90 Tage) und automatisiere den Prozess nach Möglichkeit.

Nie in Versionskontrolle committen

Tokens sollten niemals in Code-Repositories, in Git eingecheckten Konfigurationsdateien oder Build-Artefakten auftauchen. Verwende .gitignore, um Dateien mit Tokens auszuschließen.

Umgebungsvariablen verwenden

Speichere Tokens in Umgebungsvariablen oder einem Secrets Manager (z. B. AWS Secrets Manager, HashiCorp Vault, GitHub Secrets) statt sie in Skripten oder Konfigurationsdateien fest einzukodieren.

Ungenutzte Tokens widerrufen

Überprüfe regelmäßig deine Token-Liste unter Settings > API & Security. Widerrufe Tokens, die nicht mehr verwendet werden oder deren Zweck nicht mehr relevant ist.

Tokens widerrufen

Um einen Server Token zu widerrufen:

1. Navigiere zu Settings > API & Security.

2. Finde den Token in der Liste.

3. Klicke auf Revoke und bestätige.

4. Der Token wird sofort ungültig. Alle Anfragen mit diesem Token erhalten eine 401 Unauthorized-Antwort.

Hinweis

Das Widerrufen eines Tokens ist dauerhaft. Wenn du wieder Zugang brauchst, erstelle einen neuen Token.

Desktop-Auth-Flow für Edge Connector

Der Edge Connector nutzt einen speziellen Desktop-Authentifizierungsflow, um JWT Tokens ohne Server-Token-Verwaltung zu erhalten:

Wie es funktioniert

Der Desktop-Auth-Flow ist ein browserbasierter OAuth-Flow, der über die CLI gestartet wird:

1. Der Edge Connector sendet eine Anfrage an die Plattform mit einem Gerätenamen und einer Geräte-ID.
2. Die Plattform gibt einen Autorisierungscode und eine Browser-URL zurück.
3. Die CLI öffnet den Browser, wo sich der Benutzer anmeldet und die Verbindung genehmigt.
4. Die CLI erhält ein JWT Token und speichert es lokal für nachfolgende API-Aufrufe.

Dieser Flow eignet sich ideal für Desktop- und On-Premises-Installationen, bei denen ein interaktiver Login möglich ist.

Wann welche Methode

Szenario	Empfohlene Auth-Methode
Web-Anwendungs-Login	Web-Login (automatisch)
Desktop Edge Connector	Desktop-Auth-Flow (Browser OAuth)
Headless-Server Edge Connector	Deployment Credentials (ID + Secret)
CI/CD-Pipelines	Server Token
Monitoring-Skripte	Server Token
Drittanbieter-Integrationen	Server Token

Detaillierte Informationen zu den Authentifizierungsmodi des Edge Connectors findest du auf der Seite Edge Connector Authentication.

Nächste Schritte

Edge Connector Authentication Ausführliche Anleitung zu den Authentifizierungsmodi und der Token-Verwaltung des Edge Connectors.

Organisation Organisationseinstellungen und Mitgliederzugriff verwalten.

Rollen & Berechtigungen Steuern, wer Tokens erstellen und auf Sicherheitseinstellungen zugreifen kann.