Sitzungs-API

Die Sitzungs-API bietet Sichtbarkeit und Kontrolle über Benutzersitzungen im gesamten Tenant. Administratoren können aktive Sitzungen auflisten, Sitzungsdetails einsehen, einzelne Sitzungen oder alle Sitzungen eines Benutzers widerrufen und Sitzungslebensdauer-Richtlinien konfigurieren.

Eine Sitzung wird erstellt, wenn ein Benutzer sich erfolgreich authentifiziert (per Passwort, Magic Link, Social Login oder SSO). Jede Sitzung verfolgt das Gerät, die IP-Adresse, den Zeitpunkt der letzten Aktivität und die verwendete Authentifizierungsmethode. Sitzungen bleiben aktiv, bis sie ablaufen, von einem Administrator widerrufen werden oder der Benutzer sich abmeldet.

Sitzungsverwaltung

Sitzungen auflisten

GET/api/sessionsRequires: manage:sessions

Sitzungen im gesamten Tenant auflisten. Unterstützt Filterung nach Benutzer-ID und aktivem/inaktivem Status. Gibt Sitzungsmetadaten einschließlich Geräteinformationen, IP-Adresse und Authentifizierungsmethode zurück. Sitzungen sind nach dem Zeitpunkt der letzten Aktivität absteigend sortiert.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20, max: 100)
`userId`	string	Sitzungen für einen bestimmten Benutzer filtern
`active`	boolean	`true` für nur aktive Sitzungen, `false` für abgelaufene/widerrufene

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "sess_abc123",
        "userId": "usr_xyz789",
        "userEmail": "[email protected]",
        "userName": "Alice Smith",
        "ipAddress": "203.0.113.50",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
        "device": "Chrome on macOS",
        "authMethod": "password",
        "isActive": true,
        "createdAt": "2025-02-18T08:00:00Z",
        "lastActivityAt": "2025-02-18T09:45:00Z",
        "expiresAt": "2025-02-19T08:00:00Z"
      },
      {
        "id": "sess_def456",
        "userId": "usr_abc123",
        "userEmail": "[email protected]",
        "userName": "Bob Jones",
        "ipAddress": "198.51.100.42",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_3 like Mac OS X) AppleWebKit/605.1.15",
        "device": "Safari on iOS",
        "authMethod": "magic_link",
        "isActive": true,
        "createdAt": "2025-02-18T07:30:00Z",
        "lastActivityAt": "2025-02-18T09:30:00Z",
        "expiresAt": "2025-02-19T07:30:00Z"
      },
      {
        "id": "sess_ghi789",
        "userId": "usr_xyz789",
        "userEmail": "[email protected]",
        "userName": "Alice Smith",
        "ipAddress": "203.0.113.51",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "device": "Edge on Windows",
        "authMethod": "sso",
        "isActive": false,
        "revokedAt": "2025-02-17T16:00:00Z",
        "revokedBy": "usr_admin001",
        "createdAt": "2025-02-17T08:00:00Z",
        "lastActivityAt": "2025-02-17T15:55:00Z",
        "expiresAt": "2025-02-18T08:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

Authentifizierungsmethoden: password, magic_link, social, sso, device_code, m2m.

Sitzung abrufen

GET/api/sessions/[id]Requires: manage:sessions

Detaillierte Informationen über eine bestimmte Sitzung abrufen, einschließlich des vollständigen User-Agent-Strings, des Authentifizierungskontexts und der Widerrufdetails, falls die Sitzung widerrufen wurde.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "sess_abc123",
    "userId": "usr_xyz789",
    "userEmail": "[email protected]",
    "userName": "Alice Smith",
    "ipAddress": "203.0.113.50",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
    "device": "Chrome on macOS",
    "authMethod": "password",
    "isActive": true,
    "mfaVerified": true,
    "mfaMethod": "totp",
    "acr": "urn:auris:mfa",
    "amr": ["pwd", "otp"],
    "createdAt": "2025-02-18T08:00:00Z",
    "lastActivityAt": "2025-02-18T09:45:00Z",
    "expiresAt": "2025-02-19T08:00:00Z"
  }
}

Feld	Beschreibung
`mfaVerified`	Ob 2FA für diese Sitzung abgeschlossen wurde
`mfaMethod`	Die verwendete 2FA-Methode (`totp`, `sms`, `webauthn` oder `null`)
`acr`	Authentication Context Class Reference (OIDC-Claim)
`amr`	Authentication Methods Reference Array (OIDC-Claim)

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	Sitzung existiert nicht oder gehört zu einem anderen Tenant

Sitzung widerrufen

DELETE/api/sessions/[id]Requires: manage:sessions

Eine bestimmte Sitzung widerrufen. Das zugehörige Refresh-Token wird sofort ungültig. Das Zugriffs-Token bleibt bis zum natürlichen Ablauf gültig (JWTs sind zustandslos). Für sofortige Sperrung die Sitzungswiderrufung mit kurzen Zugriffs-Token-Laufzeiten kombinieren.

Zugriffs-Token sind JWTs und können nicht einzeln ohne eine Blocklist widerrufen werden. Auris verlässt sich auf kurze Zugriffs-Token-Laufzeiten (Standard: 15 Minuten) für die Sicherheit. Wenn eine Sitzung widerrufen wird, wird das Refresh-Token ungültig, sodass der Benutzer nach Ablauf des aktuellen Zugriffs-Tokens kein neues erhalten kann.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "revoked": true,
    "sessionId": "sess_abc123"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	Sitzung existiert nicht
`ALREADY_REVOKED`	400	Sitzung wurde bereits widerrufen

Alle Benutzersitzungen widerrufen

POST/api/sessions/revoke-allRequires: manage:sessions

Alle aktiven Sitzungen für einen bestimmten Benutzer widerrufen. Dies ist nützlich, wenn ein Konto kompromittiert sein könnte oder wenn ein Administrator einen Benutzer zur erneuten Authentifizierung auf allen Geräten zwingen muss. Alle zugehörigen Refresh-Token werden sofort ungültig.

Anforderungs-Body


{
  "userId": "usr_xyz789"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "revoked": true,
    "sessionsRevoked": 3,
    "userId": "usr_xyz789"
  }
}

Der sessionsRevoked-Wert gibt an, wie viele aktive Sitzungen beendet wurden.

Fehlercodes

Code	HTTP	Beschreibung
`VALIDATION_ERROR`	400	Fehlendes Feld `userId`
`NOT_FOUND`	404	Benutzer existiert nicht in diesem Tenant
`NO_ACTIVE_SESSIONS`	400	Benutzer hat keine aktiven Sitzungen zum Widerrufen

Das Widerrufen aller Sitzungen meldet den Benutzer von jedem Gerät und Browser ab. Er muss sich auf jedem neu authentifizieren. Erwäge, den Benutzer per E-Mail zu benachrichtigen, wenn du diese Aktion durchführst.

Sitzungsstatistiken

GET/api/sessions/statsRequires: manage:sessions

Aggregierte Sitzungsstatistiken für den Tenant abrufen. Nützlich zur Überwachung aktiver Benutzer und zur Identifizierung von Trends.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "activeSessions": 156,
    "uniqueUsers": 89,
    "last24Hours": {
      "newSessions": 42,
      "expiredSessions": 31,
      "revokedSessions": 3
    },
    "byAuthMethod": {
      "password": 98,
      "magic_link": 23,
      "social": 25,
      "sso": 10
    },
    "byDevice": {
      "desktop": 87,
      "mobile": 52,
      "tablet": 12,
      "unknown": 5
    }
  }
}

Sitzungsrichtlinien

Sitzungsrichtlinien steuern die Lebensdauer von Sitzungen und Token im gesamten Tenant. Diese Einstellungen gelten für alle Benutzer, sofern sie nicht durch anwendungsspezifische Konfiguration überschrieben werden.

Sicherheitseinstellungen abrufen

GET/api/settings/securityRequires: manage:security_settings

Die aktuellen Sitzungs- und Sicherheitsrichtlinieneinstellungen für den Tenant abrufen.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "sessionMaxLifetime": 86400,
    "sessionIdleTimeout": 3600,
    "refreshTokenExpiry": 604800,
    "accessTokenExpiry": 900,
    "maxConcurrentSessions": 5,
    "requireMfaForAdmin": true,
    "passwordMinLength": 8,
    "passwordRequireUppercase": true,
    "passwordRequireLowercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSpecial": false,
    "passwordHistoryCount": 5,
    "lockoutThreshold": 5,
    "lockoutDuration": 900,
    "updatedAt": "2025-02-10T14:00:00Z"
  }
}

Sitzungs- und Token-Einstellungen

Feld	Typ	Standard	Beschreibung
`sessionMaxLifetime`	integer	`86400` (24h)	Maximale Sitzungsdauer in Sekunden, unabhängig von der Aktivität
`sessionIdleTimeout`	integer	`3600` (1h)	Sitzung läuft nach dieser Inaktivitätsdauer in Sekunden ab
`refreshTokenExpiry`	integer	`604800` (7d)	Refresh-Token-Laufzeit in Sekunden
`accessTokenExpiry`	integer	`900` (15m)	Zugriffs-Token-Laufzeit in Sekunden
`maxConcurrentSessions`	integer	`5`	Maximale aktive Sitzungen pro Benutzer (0 = unbegrenzt)

MFA-Einstellungen

Feld	Typ	Standard	Beschreibung
`requireMfaForAdmin`	boolean	`true`	2FA für Benutzer mit Admin-Rollen verlangen

Passwortrichtlinieneinstellungen

Feld	Typ	Standard	Beschreibung
`passwordMinLength`	integer	`8`	Mindestlänge des Passworts
`passwordRequireUppercase`	boolean	`true`	Mindestens einen Großbuchstaben verlangen
`passwordRequireLowercase`	boolean	`true`	Mindestens einen Kleinbuchstaben verlangen
`passwordRequireNumbers`	boolean	`true`	Mindestens eine Ziffer verlangen
`passwordRequireSpecial`	boolean	`false`	Mindestens ein Sonderzeichen verlangen
`passwordHistoryCount`	integer	`5`	Anzahl der zu prüfenden vorherigen Passwörter (0 = deaktiviert)

Sperreinstellungen

Feld	Typ	Standard	Beschreibung
`lockoutThreshold`	integer	`5`	Anzahl fehlgeschlagener Anmeldeversuche vor Sperrung
`lockoutDuration`	integer	`900` (15m)	Sperrdauer in Sekunden

Sicherheitseinstellungen aktualisieren

PUT/api/settings/securityRequires: manage:security_settings

Sitzungs- und Sicherheitsrichtlinieneinstellungen aktualisieren. Alle Felder sind optional — nur angegebene Felder werden aktualisiert. Änderungen wirken sich sofort auf neue Sitzungen aus. Bestehende Sitzungen werden nicht rückwirkend beeinflusst (sie laufen mit ihren ursprünglichen Ablaufzeiten weiter).

Anforderungs-Body


{
  "sessionMaxLifetime": 43200,
  "accessTokenExpiry": 600,
  "maxConcurrentSessions": 3,
  "requireMfaForAdmin": true,
  "passwordMinLength": 12,
  "lockoutThreshold": 3,
  "lockoutDuration": 1800
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "sessionMaxLifetime": 43200,
    "sessionIdleTimeout": 3600,
    "refreshTokenExpiry": 604800,
    "accessTokenExpiry": 600,
    "maxConcurrentSessions": 3,
    "requireMfaForAdmin": true,
    "passwordMinLength": 12,
    "passwordRequireUppercase": true,
    "passwordRequireLowercase": true,
    "passwordRequireNumbers": true,
    "passwordRequireSpecial": false,
    "passwordHistoryCount": 5,
    "lockoutThreshold": 3,
    "lockoutDuration": 1800,
    "updatedAt": "2025-02-18T11:00:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`VALIDATION_ERROR`	400	Ungültiger Wert (z. B. negative Zahl, `accessTokenExpiry` > `sessionMaxLifetime`)

Validierungsregeln

accessTokenExpiry muss zwischen 60 (1 Minute) und 86400 (24 Stunden) liegen
refreshTokenExpiry muss zwischen 3600 (1 Stunde) und 2592000 (30 Tage) liegen
sessionMaxLifetime muss >= accessTokenExpiry sein
sessionIdleTimeout muss <= sessionMaxLifetime sein
maxConcurrentSessions muss zwischen 0 und 100 liegen
passwordMinLength muss zwischen 6 und 128 liegen
lockoutThreshold muss zwischen 1 und 100 liegen
lockoutDuration muss zwischen 60 (1 Minute) und 86400 (24 Stunden) liegen

Sehr kurze Zugriffs-Token-Laufzeiten (unter 5 Minuten) erhöhen die Häufigkeit von Token-Aktualisierungsanfragen. Sehr lange Laufzeiten verringern die Sicherheit. Der empfohlene Bereich liegt zwischen 5 und 30 Minuten.

Durchsetzung gleichzeitiger Sitzungen

Wenn maxConcurrentSessions auf einen Wert ungleich null gesetzt ist, erzwingt Auris eine Begrenzung der Anzahl aktiver Sitzungen pro Benutzer. Wenn eine neue Sitzung erstellt wird und der Benutzer bereits die maximale Anzahl an Sitzungen hat:

Die älteste Sitzung (nach createdAt) wird automatisch widerrufen.
Die neue Sitzung wird normal erstellt.
Der Benutzer erhält eine Benachrichtigung, dass eine ältere Sitzung beendet wurde (falls In-App-Benachrichtigungen aktiviert sind).

Dieses Verhalten stellt sicher, dass Benutzer nie aufgrund veralteter Sitzungen an der Anmeldung gehindert werden, während dennoch eine vernünftige Obergrenze für den gleichzeitigen Zugriff eingehalten wird.

Sitzungslebenszyklus


Benutzer authentifiziert sich
       |
       v
  Sitzung erstellt (isActive: true)
       |
       +--- Benutzer stellt API-Anfragen ---> lastActivityAt aktualisiert
       |
       +--- Zugriffs-Token abgelaufen ---> Benutzer erneuert Token
       |         (refreshToken noch gültig)
       |
       +--- Idle-Timeout erreicht ---> Sitzung abgelaufen
       |
       +--- Maximale Lebensdauer erreicht ---> Sitzung abgelaufen
       |
       +--- Admin widerruft Sitzung ---> Sitzung widerrufen
       |
       +--- Benutzer meldet sich ab ---> Sitzung widerrufen
       |
       v
  Sitzung inaktiv (isActive: false)

Berechtigungsreferenz

Berechtigung	Beschreibung
`manage:sessions`	Sitzungen im gesamten Tenant auflisten, einsehen und widerrufen
`manage:security_settings`	Sitzungsrichtlinien und Sicherheitseinstellungen anzeigen und aktualisieren

Einzelne Benutzer können ihre eigenen Sitzungen über die Benutzerprofil-Endpunkte (GET /api/user/sessions, DELETE /api/user/sessions/[id]) anzeigen und widerrufen, ohne Admin-Berechtigungen zu benötigen. Die auf dieser Seite dokumentierten Endpunkte dienen der mandantenweiten Verwaltung.

Sitzungs-API

Sitzungsverwaltung

Sitzungen auflisten

Sitzung abrufen

Sitzung widerrufen

Alle Benutzersitzungen widerrufen

Sitzungsstatistiken

Sitzungsrichtlinien

Sicherheitseinstellungen abrufen

Sicherheitseinstellungen aktualisieren

Durchsetzung gleichzeitiger Sitzungen

Sitzungslebenszyklus

Berechtigungsreferenz

Verwandte Themen