Tokens & API-Keys¶
Drei Arten von Zugangsdaten: Anmelde-Token der Benutzer, Agent-Tokens und Collector-API-Keys.
Anmelde-Token (Benutzer)¶
Nach Login (und 2FA) bekommt der Benutzer signierte JWTs. Zwei Wege:
| Browser (Weboberfläche) | API / Mobile-App (Bearer) | |
|---|---|---|
| Signatur | HS256 mit SECRET_KEY aus der .env |
HS256 mit SECRET_KEY |
| Zugangs-Token | 30 Minuten, im Cookie vesana_access |
12 Stunden, Header Authorization: Bearer … |
| Verlängerung | still über das Cookie vesana_refresh (rotiert bei jeder Verlängerung) |
über /api/v1/auth/refresh, begrenzt durch die Höchstdauer der Sitzung |
| Speicherung | HttpOnly-Cookies (Secure, SameSite=Strict) — JavaScript kommt nicht an die Token |
beim Aufrufer |
| Inhalt | Benutzer-ID, E-Mail, Rolle, Mandant, Rechte (bei Super-Admins nicht — die leitet der Server ab), Rechte-Stand | wie Browser |
Die Sitzung selbst lebt serverseitig. Wie lange sie hält (Standard: 30 Tage ohne Nutzung, höchstens 90 Tage), stellst du unter Admin → Anmeldung & Sicherheit → 2FA & Sitzungen ein — siehe Login-Sitzungen.
Widerruf¶
Abmelden, „Überall sonst abmelden", Passwortwechsel, Deaktivieren eines Kontos und Rechte-Änderungen wirken innerhalb von Sekunden: der Server prüft bei jeder Anfrage, ob die Sitzung widerrufen ist und ob der Rechte-Stand im Token noch aktuell ist. Ein erkannter Wiedergebrauch eines schon rotierten Verlängerungs-Tokens (Hinweis auf Diebstahl) beendet die Sitzung.
SECRET_KEY schützt alle Anmeldungen
Wer den SECRET_KEY kennt, kann gültige Anmelde-Token für jedes Konto ausstellen. Er steht in der .env (Rechte 600, siehe Härtungs-Checkliste). Ein neuer SECRET_KEY meldet alle Benutzer ab.
Agent-Token¶
Für Agents auf überwachten Maschinen.
| Feld | Wert |
|---|---|
| Format | vesana_agent_ + 43 Zeichen (32 Zufallsbytes, URL-sicheres Base64) |
| Speicherung Server | nur als SHA-256-Hash |
| Speicherung Agent | Klartext in der Agent-Config: Linux /etc/vesana-agent/config.yaml (Rechte 600), Windows C:\ProgramData\Vesana\Agent\config.yaml (nur Administratoren und SYSTEM) |
| Lebensdauer | unbegrenzt, bis zum Widerruf |
| Bindung | an genau einen Host; ein neues Token macht das vorige ungültig |
| Auth-Header | X-Agent-Token: vesana_agent_… |
Erzeugen¶
In der Oberfläche über Agent einrichten am Host (Recht agents.manage). Der Klartext wird genau einmal angezeigt; gespeichert wird nur der Hash.
Erneuern und widerrufen¶
Host-Detail → Host verwalten → Token erneuern stellt ein neues Token aus; das alte ist sofort ungültig, der Agent muss mit dem neuen Token neu installiert werden (oder du setzt es von Hand in der Config und startest den Dienst neu). Token widerrufen (bzw. Agent entfernen am Agent-Chip) sperrt den Agent aus, ohne ein neues Token auszustellen.
Der Empfänger merkt sich gültige Anmeldungen bis zu 60 Sekunden; ein Widerruf greift trotzdem nach spätestens einer Sekunde.
Collector-API-Key¶
Für Collectors im Kundennetz.
| Feld | Wert |
|---|---|
| Format | vesana_ + 43 Zeichen (32 Zufallsbytes, URL-sicheres Base64) |
| Speicherung Server | nur als SHA-256-Hash |
| Speicherung Collector | Klartext in /etc/vesana/collector.env |
| Auth-Header | X-API-Key: vesana_… |
| Bindung | an genau einen Collector |
Der Key entsteht beim Anlegen des Collectors und wird einmal angezeigt (im Installationsbefehl). Key erneuern am Collector (Recht collectors.edit plus Identitätsbestätigung) deaktiviert den alten Key sofort; der Collector muss danach mit dem neuen Key neu installiert werden. Die Anmeldung prüft ausschließlich den Hash des vollständigen Keys — die ersten Zeichen, die in Listen angezeigt werden, dienen nur zum Unterscheiden.
Persönliche API-Keys für Benutzer gibt es nicht. Skripte und Integrationen melden sich wie die Oberfläche an und nutzen das Bearer-Token (siehe API → Authentifizierung).
Hashing¶
Agent-Tokens und API-Keys liegen nur als SHA-256-Hash in der Datenbank. Ein Datenbank-Leck verrät damit kein funktionierendes Token. Ein Salt ist nicht nötig, weil die Tokens selbst 32 Zufallsbytes tragen.
Nur über HTTPS¶
Vesana erzeugt beim ersten Start ein selbstsigniertes Zertifikat, HTTPS ist also immer verfügbar. Der HTTP-Port leitet jede Anfrage auf HTTPS um (301) — nur der Pfad für die Let's-Encrypt-Prüfung bleibt auf HTTP. Für Produktion: ein Zertifikat aus Vesana (Let's Encrypt) oder ein eigenes, siehe TLS / Zertifikat.
Audit¶
Token-Vorgänge stehen im Audit-Log, u. a. agent_token_create, agent_token_revoke, collector_create und collector_regenerate_key.