Tokens erklärt

Auris verwendet drei Kategorien von Tokens: Zugriffstoken, Refresh-Token und ID-Token. Das Verständnis, wofür jedes Token bestimmt ist, was es enthält und wie es behandelt werden sollte, ist für die Entwicklung sicherer Integrationen unerlässlich.

Zugriffstoken

Das Zugriffstoken ist die Anmeldeinformation, die deine Anwendung verwendet, um geschützte APIs aufzurufen. Es ist bewusst kurzlebig — die Standard-Ablaufzeit beträgt 15 Minuten.

Was es ist

Ein Zugriffstoken ist ein signiertes JWT (JSON Web Token). Es ist in sich geschlossen: Der Ressourcenserver kann seine Authentizität durch Prüfung der Signatur verifizieren, ohne einen Netzwerkaufruf zu Auris zu tätigen, unter Verwendung der öffentlichen Schlüssel vom JWKS-Endpunkt.

Was es enthält

Eine dekodierte Auris-Zugriffstoken-Payload sieht so aus:


{
  "sub": "usr_abc123",
  "iss": "https://api.altovar.net",
  "aud": "your-client-id",
  "iat": 1739880000,
  "exp": 1739880900,
  "jti": "tok_xyz789",
  "type": "user",
  "email": "[email protected]",
  "roles": ["editor", "viewer"],
  "scope": "openid profile email",
  "plan": "enterprise"
}

Claim	Beschreibung
`sub`	Subject — die Benutzer-ID (eindeutig innerhalb des Tenants)
`iss`	Issuer — die Auris-Instanz-URL
`aud`	Audience — die Client-ID der Anwendung
`iat`	Issued At — Unix-Zeitstempel der Token-Ausstellung
`exp`	Expiry — Unix-Zeitstempel des Token-Ablaufs
`jti`	JWT ID — eindeutiger Bezeichner für dieses Token
`type`	`"user"` für reguläre Benutzer, `"m2m"` für Client-Credentials-Tokens
`email`	E-Mail-Adresse des Benutzers
`roles`	Array der dem Benutzer zugewiesenen Rollennamen
`scope`	Leerzeichen-getrennte gewährte Scopes
Benutzerdefinierte Claims	Alle über Custom Claims in der Konsole konfigurierten zusätzlichen Claims

Verwendung

Sende das Zugriffstoken im Authorization-Header bei jeder Anfrage an eine geschützte API:


Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImtleS1pZC0xIn0...

Bei Ablauf

Zugriffstoken laufen standardmäßig nach 15 Minuten ab. Wenn eine API 401 Unauthorized mit dem Fehlercode TOKEN_EXPIRED zurückgibt, verwende den Refresh-Token, um ein neues Zugriffstoken zu erhalten. Die Auris SDKs behandeln dies automatisch, wenn autoRefresh: true konfiguriert ist.

Refresh-Token

Der Refresh-Token ermöglicht es deiner Anwendung, neue Zugriffstoken zu erhalten, ohne dass der Benutzer sich erneut anmelden muss.

Was es ist

Ein Refresh-Token ist ein opaker String — er enthält keine Claims und kann nicht dekodiert werden. Es handelt sich um einen zufälligen Wert, den Auris intern speichert und validiert. Seine Opazität ist beabsichtigt: Er muss an Auris zurückgesendet werden, um irgendetwas Nützliches zu erhalten.

Ein Refresh-Token sieht so aus:


rt_7fKp2mXa9qN3vB8yR4tL1wC6jD5sE0uH

Standard-Lebensdauer

Refresh-Token laufen standardmäßig nach 7 Tagen Inaktivität ab. Wenn der Benutzer aktiv ist, wird das Token bei jeder Verwendung rotiert und die Ablaufzeit zurückgesetzt. Tenant-Administratoren können die Ablaufzeit in der Auris-Konsole unter Einstellungen → Sicherheit → Sitzungsrichtlinien konfigurieren.

Rotation

Auris verwendet Refresh-Token-Rotation: Jedes Mal, wenn du einen Refresh-Token gegen neue Tokens austauschst, wird der alte Refresh-Token sofort ungültig und ein neuer ausgestellt. Dies begrenzt das Expositionsfenster, falls ein Refresh-Token gestohlen wird.


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_NEW_rotated_token...",
    "expiresIn": 900
  }
}

Sicherheitserwägungen

Speichere Refresh-Token wenn möglich in httpOnly-Cookies (für JavaScript nicht zugänglich)
Wenn du in Memory oder localStorage speicherst, akzeptierst du den XSS-Risikokompromiss
Niemals Refresh-Token in URLs oder Protokolldateien aufnehmen
Die kurze Lebensdauer des Zugriffstokens begrenzt den Schaden bei Abfangen — der Refresh-Token ist die höherwertige Anmeldeinformation

ID-Token

Das ID-Token ist ein OIDC-Konzept. Es wird zusammen mit dem Zugriffstoken ausgestellt, wenn der openid-Scope angefordert wird.

Was es ist

Ein ID-Token ist ein signiertes JWT, das die Identitäts-Claims des Benutzers enthält. Es ist zur Verwendung durch die Client-Anwendung gedacht — nicht zum Senden an APIs. APIs sollten das Zugriffstoken verifizieren, nicht das ID-Token.

Was es enthält


{
  "sub": "usr_abc123",
  "iss": "https://api.altovar.net",
  "aud": "your-client-id",
  "iat": 1739880000,
  "exp": 1739883600,
  "email": "[email protected]",
  "email_verified": true,
  "name": "Alice Smith",
  "given_name": "Alice",
  "family_name": "Smith",
  "picture": "https://cdn.example.com/avatars/alice.jpg"
}

Das ID-Token hat eine längere Lebensdauer als das Zugriffstoken (typischerweise 1 Stunde), da es nur für Anzeigeoperationen im Client verwendet wird, nicht für API-Aufrufe.

Wann zu verwenden

Name und Avatar des Benutzers in deiner UI ohne extra API-Aufruf anzeigen
Identität des Benutzers in einer serverseitig gerenderten Anwendung verifizieren
Benutzerkontext an Drittanbieter-Widgets weitergeben, die OIDC-Tokens akzeptieren

Verwende das ID-Token nicht zur Autorisierung von API-Aufrufen.

JWT-Struktur

Alle JWTs (Zugriffstoken und ID-Token) teilen dieselbe dreiteilige Struktur, getrennt durch Punkte:


header.payload.signature

Jeder Teil ist Base64URL-kodiert (URL-sicheres Base64 ohne Padding). Die drei Teile sind:

Header


{
  "alg": "RS256",
  "kid": "key-id-1",
  "typ": "JWT"
}

Feld	Beschreibung
`alg`	Signaturalgorithmus (`RS256` oder `HS256`)
`kid`	Key ID — identifiziert, welcher öffentliche Schlüssel zur Verifizierung verwendet werden soll (aus JWKS)
`typ`	Token-Typ — immer `JWT`

Payload

Das oben beschriebene Claims-Objekt.

Signatur

Für RS256: RSASHA256(base64url(header) + "." + base64url(payload), privateKey)

Die Signatur stellt sicher, dass das Token nicht manipuliert wurde. Jeder kann Header und Payload dekodieren (sie sind nur Base64), aber nur Auris (im Besitz des privaten Schlüssels) kann eine gültige Signatur erzeugen.

Das Dekodieren eines JWT validiert es nicht. Verifiziere immer die Signatur gegen den öffentlichen Schlüssel, bevor du den Claims vertraust. Verwende eine JWT-Bibliothek oder das Auris SDK — niemals Tokens in Produktionscode manuell ohne Verifizierung dekodieren.

Signaturalgorithmen

Auris unterstützt zwei Signaturalgorithmen, konfiguriert über die Umgebungsvariable JWT_ALGORITHM:

RS256 (empfohlen)

RSA + SHA-256. Asymmetrisch — Auris signiert mit einem privaten Schlüssel, Ressourcenserver verifizieren mit dem öffentlichen Schlüssel. Der öffentliche Schlüssel wird über den JWKS-Endpunkt bereitgestellt.

Vorteile:

Ressourcenserver können Tokens lokal ohne Kontaktaufnahme mit Auris verifizieren
Der private Schlüssel verlässt nie den Auris-Server
Standardunterstützung in allen wichtigen JWT-Bibliotheken
Kompatibel mit allen Standard-OIDC-Bibliotheken

HS256

HMAC + SHA-256. Symmetrisch — dasselbe Secret wird sowohl für Signatur als auch Verifizierung verwendet. Sowohl Auris als auch der Ressourcenserver müssen das gemeinsame Secret kennen.

Auris unterstützt HS256 für die Kompatibilität mit bestimmten Legacy-Integrationen. RS256 wird für neue Deployments dringend bevorzugt.

JWKS-Verifizierung

Ressourcenserver verifizieren Zugriffstoken, indem sie die Signaturschlüssel vom JWKS-Endpunkt abrufen und diese zur lokalen Validierung der JWT-Signatur verwenden.

JWKS-Endpunkt


GET /.well-known/jwks.json

Antwort


{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM...",
      "e": "AQAB"
    }
  ]
}

Verifizierungsschritte

JWT-Header dekodieren (ohne Signaturverifizierung), um die kid (Key ID) zu extrahieren
JWKS-Endpunkt abrufen (oder gecachte Version verwenden — empfohlene TTL: 1 Stunde)
Den Schlüssel in der JWKS-Antwort finden, dessen kid mit der kid des Headers übereinstimmt
Diesen öffentlichen Schlüssel zur Verifizierung der JWT-Signatur verwenden
Verifizieren, dass exp in der Zukunft liegt, iss mit deiner Auris-Domain übereinstimmt, aud mit deiner Client-ID übereinstimmt

Die meisten JWT-Bibliotheken führen die Schritte 1-5 automatisch durch, wenn eine JWKS-URL angegeben wird. Beispiel mit der jose-Bibliothek:


import { createRemoteJWKSet, jwtVerify } from 'jose'
 
const JWKS = createRemoteJWKSet(
  new URL('https://api.altovar.net/.well-known/jwks.json')
)
 
async function verifyToken(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: 'https://api.altovar.net',
    audience: 'your-client-id',
  })
  return payload
}

Schlüsselrotation

Auris rotiert periodisch Signaturschlüssel, um die Auswirkungen einer Schlüsselkompromittierung zu begrenzen. Der Rotationsprozess:

Ein neues RSA-Schlüsselpaar wird generiert und dem JWKS-Endpunkt mit einer neuen kid hinzugefügt
Neue Tokens werden mit dem neuen Schlüssel signiert
Alte Tokens (mit dem alten Schlüssel signiert) bleiben gültig, weil der alte öffentliche Schlüssel in der JWKS-Antwort verbleibt
Der alte Schlüssel wird erst dann aus JWKS entfernt, wenn alle damit signierten Tokens abgelaufen sind

Das bedeutet, der JWKS-Endpunkt kann gleichzeitig mehrere Schlüssel zurückgeben. Clients müssen den Schlüssel anhand der kid nachschlagen, nicht immer den ersten Schlüssel im Array verwenden.

Token-Lebenszyklus

Das Verständnis des vollständigen Token-Lebenszyklus hilft dir, Randfälle korrekt zu behandeln:


Login
  → Zugriffstoken (15 Min.) + Refresh-Token (7 Tage) + ID-Token (1 Std.) erhalten
  ↓
Zugriffstoken bei API-Aufrufen verwenden
  ↓
Zugriffstoken läuft ab (401 TOKEN_EXPIRED)
  ↓
Refresh-Token austauschen → neues Zugriffstoken + neuer Refresh-Token
  ↓
Neues Zugriffstoken weiter verwenden
  ↓
Benutzer meldet sich ab / Refresh-Token läuft ab / Refresh-Token widerrufen
  ↓
Benutzer muss sich erneut authentifizieren

Best Practices zur Speicherung

Browser-Anwendungen (SPA)

Speicher	Sicherheit	Hinweise
`httpOnly`-Cookie	Höchste	Für JavaScript nicht zugänglich — schützt gegen XSS. Erfordert Same-Site- oder CORS-Einrichtung.
`sessionStorage`	Mittel	Wird beim Schließen des Tabs gelöscht. Anfällig für XSS.
`localStorage`	Mittel	Bleibt sitzungsübergreifend erhalten. Anfällig für XSS.
URL-Fragment / Query-String	Niedrigste	Niemals tun — Tokens erscheinen im Browser-Verlauf und Server-Protokollen

Das Auris SDK speichert Tokens standardmäßig in localStorage aus Gründen der Bequemlichkeit. Konfiguriere für höhere Sicherheitsanforderungen das SDK zur Verwendung des CookieBridgeStorage-Adapters, der über einen Same-Origin-Endpunkt in httpOnly-Cookies schreibt.

Server-seitige Anwendungen

Speichere den Refresh-Token in der serverseitigen Sitzung des Benutzers (verschlüsselt im Ruhezustand). Stelle kurzlebige Zugriffstoken bei Bedarf aus und cache sie für ihre verbleibende Lebensdauer im Speicher. Speichere niemals Zugriffstoken in der Datenbank.

Mobile Anwendungen

Verwende den sicheren Anmeldeinformation-Speicher der Plattform:

iOS: Keychain Services
Android: Android Keystore
React Native: react-native-keychain oder Expo SecureStore

Speichere niemals Tokens in AsyncStorage auf mobilen Geräten — es ist nicht verschlüsselt.

Das Auris React SDK (@auris/react) verwaltet die Token-Speicherung automatisch. Sofern du keine benutzerdefinierte Integration implementierst, musst du dich nicht selbst um die Token-Speicherung kümmern.

Tokens erklärt

Zugriffstoken

Was es ist

Was es enthält

Verwendung

Bei Ablauf

Refresh-Token

Was es ist

Standard-Lebensdauer

Rotation

Sicherheitserwägungen

ID-Token

Was es ist

Was es enthält

Wann zu verwenden

JWT-Struktur

Header

Payload

Signatur

Signaturalgorithmen

RS256 (empfohlen)

HS256

JWKS-Verifizierung

JWKS-Endpunkt

Antwort

Verifizierungsschritte

Schlüsselrotation

Token-Lebenszyklus

Best Practices zur Speicherung

Browser-Anwendungen (SPA)

Server-seitige Anwendungen

Mobile Anwendungen

Verwandte Konzepte