Sicherheits-API

Die Sicherheits-API bietet Werkzeuge zum Schutz des Tenants vor unbefugtem Zugriff und bösartiger Aktivität. Administratoren können IP-Erlaubnis-/Sperrlisten pflegen, verdächtige Anmeldeereignisse überprüfen, CAPTCHA-Verifizierung konfigurieren und Kontosperrungen verwalten.

Auris wertet Sicherheitsregeln bei jedem Authentifizierungsversuch in dieser Reihenfolge aus: IP-Regeln (blockieren/erlauben) → CAPTCHA-Verifizierung → Rate Limiting → Anmeldeinformationsvalidierung → Analyse verdächtiger Anmeldungen → adaptives MFA. Jede Schicht arbeitet unabhängig und kann separat konfiguriert werden.

IP-Regeln

IP-Regeln definieren Erlaubnis- und Sperrlisten mit CIDR-Notation. Sperrregeln haben immer Vorrang vor Erlaubnisregeln. Regeln können auf den gesamten Tenant oder auf eine bestimmte Anwendung beschränkt werden.

IP-Regeln auflisten

GET/api/ip-rulesRequires: manage:users

Alle für den Tenant konfigurierten IP-Erlaubnis-/Sperrregeln auflisten. Unterstützt Filterung nach Regeltyp, Geltungsbereich und aktivem Status. Regeln sind nach Erstellungsdatum absteigend sortiert.

Abfrageparameter

Parameter	Typ	Beschreibung
`type`	string	Nach Regeltyp filtern: `ALLOW` oder `BLOCK`
`scope`	string	Nach Geltungsbereich filtern: `TENANT` oder `APPLICATION`
`isActive`	boolean	Nach aktivem Status filtern
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20, max: 100)

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "ipr_abc123",
        "cidr": "203.0.113.0/24",
        "type": "BLOCK",
        "scope": "TENANT",
        "applicationId": null,
        "label": "Bekannter Angreifer-Bereich",
        "note": "Blockiert nach Brute-Force-Kampagne am 2025-02-10",
        "isTemporary": true,
        "expiresAt": "2025-03-10T00:00:00Z",
        "isActive": true,
        "createdAt": "2025-02-10T14:30:00Z",
        "updatedAt": "2025-02-10T14:30:00Z"
      },
      {
        "id": "ipr_def456",
        "cidr": "10.0.0.0/8",
        "type": "ALLOW",
        "scope": "TENANT",
        "applicationId": null,
        "label": "Unternehmens-VPN",
        "note": "Interner Netzwerkbereich",
        "isTemporary": false,
        "expiresAt": null,
        "isActive": true,
        "createdAt": "2025-01-15T09:00:00Z",
        "updatedAt": "2025-01-15T09:00:00Z"
      },
      {
        "id": "ipr_ghi789",
        "cidr": "198.51.100.50/32",
        "type": "BLOCK",
        "scope": "APPLICATION",
        "applicationId": "app_prod001",
        "label": "Verdächtige IP",
        "note": null,
        "isTemporary": false,
        "expiresAt": null,
        "isActive": true,
        "createdAt": "2025-02-05T11:20:00Z",
        "updatedAt": "2025-02-05T11:20:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "totalPages": 1
    }
  }
}

IP-Regel erstellen

POST/api/ip-rulesRequires: manage:users

Eine neue IP-Erlaubnis- oder Sperregel erstellen. CIDR-Notation ist erforderlich — verwende /32 für eine einzelne IP-Adresse. Sperrregeln haben bei der Auswertung immer Vorrang vor Erlaubnisregeln.

Anforderungs-Body


{
  "cidr": "192.0.2.0/24",
  "type": "BLOCK",
  "scope": "TENANT",
  "label": "Rechenzentrumsbereich",
  "note": "Blockiert wegen automatisierter Scraping-Aktivität",
  "isTemporary": true,
  "expiresAt": "2025-04-01T00:00:00Z"
}

Feld	Typ	Erforderlich	Beschreibung
`cidr`	string	Ja	IP-Adresse oder -Bereich in CIDR-Notation (z. B. `10.0.0.1/32`, `192.168.0.0/16`)
`type`	string	Ja	`ALLOW` oder `BLOCK`
`scope`	string	Ja	`TENANT` (gilt für alle Apps) oder `APPLICATION` (erfordert `applicationId`)
`applicationId`	string	Nein	Erforderlich wenn Geltungsbereich `APPLICATION` ist
`label`	string	Nein	Für Menschen lesbares Label für die Regel
`note`	string	Nein	Administrative Notiz oder Begründung
`isTemporary`	boolean	Nein	Ob die Regel automatisch abläuft (Standard: `false`)
`expiresAt`	string	Nein	ISO 8601 Ablaufdatum. Erforderlich wenn `isTemporary` `true` ist

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "ipr_jkl012",
    "cidr": "192.0.2.0/24",
    "type": "BLOCK",
    "scope": "TENANT",
    "applicationId": null,
    "label": "Rechenzentrumsbereich",
    "note": "Blockiert wegen automatisierter Scraping-Aktivität",
    "isTemporary": true,
    "expiresAt": "2025-04-01T00:00:00Z",
    "isActive": true,
    "createdAt": "2025-02-18T10:00:00Z",
    "updatedAt": "2025-02-18T10:00:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`VALIDATION_ERROR`	400	Ungültige CIDR-Notation, fehlende Pflichtfelder oder ungültige Geltungsbereich/Typ-Kombination
`DUPLICATE_RULE`	409	Eine Regel mit demselben CIDR und Geltungsbereich existiert bereits

Temporäre Regeln werden nach ihrem expiresAt-Zeitstempel automatisch bereinigt. Du musst sie nicht manuell löschen.

IP-Regel aktualisieren

PATCH/api/ip-rules/[id]Requires: manage:users

Eine bestehende IP-Regel aktualisieren. Alle Felder sind optional — nur angegebene Felder werden aktualisiert. Änderungen am CIDR oder Typ einer Regel wirken sich sofort auf nachfolgende Anmeldeversuche aus.

Anforderungs-Body


{
  "label": "Aktualisiertes Label",
  "note": "Sperre nach weiterer Aktivität verlängert",
  "isActive": false
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "ipr_abc123",
    "cidr": "203.0.113.0/24",
    "type": "BLOCK",
    "scope": "TENANT",
    "applicationId": null,
    "label": "Aktualisiertes Label",
    "note": "Sperre nach weiterer Aktivität verlängert",
    "isTemporary": true,
    "expiresAt": "2025-03-10T00:00:00Z",
    "isActive": false,
    "createdAt": "2025-02-10T14:30:00Z",
    "updatedAt": "2025-02-18T10:30:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	IP-Regel existiert nicht
`VALIDATION_ERROR`	400	Ungültiger Feldwert

IP-Regel löschen

DELETE/api/ip-rules/[id]Requires: manage:users

Eine IP-Regel dauerhaft löschen. Die Regel wird sofort entfernt und bei nachfolgenden Authentifizierungsversuchen nicht mehr ausgewertet.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "deleted": true,
    "id": "ipr_abc123"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	IP-Regel existiert nicht

Verdächtige Anmeldeereignisse

Auris überwacht Anmeldeversuche auf anomales Verhalten mit fünf Erkennungsmethoden: neues Gerät, neue IP-Adresse, neues Land, unmögliche Reise und VPN-/Proxy-Nutzung. Wenn verdächtige Aktivität erkannt wird, wird ein Ereignis protokolliert und die konfigurierte Aktion ausgeführt (nur protokollieren, MFA verlangen oder blockieren).

Verdächtige Anmeldeereignisse auflisten

GET/api/suspicious-login/eventsRequires: manage:users

Verdächtige Anmeldeereignisse im gesamten Tenant auflisten. Ereignisse sind nach Erstellungsdatum absteigend sortiert. Verwende den Filter reviewed, um Ereignisse zu finden, die Administratoraufmerksamkeit erfordern.

Abfrageparameter

Parameter	Typ	Beschreibung
`userId`	string	Ereignisse für einen bestimmten Benutzer filtern
`severity`	string	Nach Schweregrad filtern: `low`, `medium`, `high`, `critical`
`reason`	string	Nach Erkennungsgrund filtern: `new_device`, `new_ip`, `new_country`, `impossible_travel`, `vpn_detected`
`reviewed`	boolean	`true` für überprüfte Ereignisse, `false` für nicht überprüfte
`page`	integer	Seitennummer (Standard: 1)
`limit`	integer	Elemente pro Seite (Standard: 20, max: 100)

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "sle_abc123",
        "userId": "usr_xyz789",
        "userEmail": "[email protected]",
        "reason": "impossible_travel",
        "severity": "high",
        "actionTaken": "require_mfa",
        "details": {
          "previousLocation": { "country": "Italy", "city": "Rome", "lat": 41.9028, "lng": 12.4964 },
          "currentLocation": { "country": "Brazil", "city": "Sao Paulo", "lat": -23.5505, "lng": -46.6333 },
          "distanceKm": 9187,
          "timeDiffMinutes": 45,
          "requiredSpeedKmh": 12249
        },
        "ipAddress": "198.51.100.42",
        "reviewed": false,
        "reviewedAt": null,
        "reviewedBy": null,
        "createdAt": "2025-02-18T09:15:00Z"
      },
      {
        "id": "sle_def456",
        "userId": "usr_abc123",
        "userEmail": "[email protected]",
        "reason": "vpn_detected",
        "severity": "medium",
        "actionTaken": "log",
        "details": {
          "ipAddress": "203.0.113.50",
          "isp": "NordVPN",
          "isVpn": true,
          "isProxy": false,
          "isDatacenter": true
        },
        "ipAddress": "203.0.113.50",
        "reviewed": true,
        "reviewedAt": "2025-02-18T10:00:00Z",
        "reviewedBy": "usr_admin001",
        "createdAt": "2025-02-18T08:45:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 47,
      "totalPages": 3
    }
  }
}

Ereignis als überprüft markieren

PATCH/api/suspicious-login/events/[id]/reviewRequires: manage:users

Ein verdächtiges Anmeldeereignis als überprüft markieren. Dies ist eine administrative Bestätigung und hat keinen Einfluss auf den Benutzerzugriff. Damit kannst du verfolgen, welche Ereignisse untersucht wurden.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "id": "sle_abc123",
    "reviewed": true,
    "reviewedAt": "2025-02-18T11:00:00Z",
    "reviewedBy": "usr_admin001"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	Ereignis existiert nicht
`ALREADY_REVIEWED`	400	Ereignis wurde bereits als überprüft markiert

Erkennungskonfiguration abrufen

GET/api/suspicious-login/configRequires: manage:users

Die aktuelle Erkennungskonfiguration für verdächtige Anmeldungen für den Tenant abrufen.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "detectNewDevice": true,
    "detectNewIp": true,
    "detectNewCountry": true,
    "detectImpossibleTravel": true,
    "detectVpn": false,
    "actionOnNewDevice": "log",
    "actionOnNewIp": "log",
    "actionOnNewCountry": "require_mfa",
    "actionOnImpossibleTravel": "require_mfa",
    "actionOnVpn": "log",
    "maxTravelSpeedKmh": 900,
    "geoIpProvider": "ip-api",
    "updatedAt": "2025-02-01T12:00:00Z"
  }
}

Feld	Typ	Beschreibung
`detectNewDevice`	boolean	Anmeldungen von bisher unbekannten Geräte-Fingerabdrücken kennzeichnen
`detectNewIp`	boolean	Anmeldungen von bisher unbekannten IP-Adressen kennzeichnen
`detectNewCountry`	boolean	Anmeldungen aus einem neuen Land kennzeichnen
`detectImpossibleTravel`	boolean	Kennzeichnen, wenn aufeinanderfolgende Anmeldungen geografisch unmöglich sind angesichts der verstrichenen Zeit
`detectVpn`	boolean	Anmeldungen von bekannten VPN-/Proxy-/Rechenzentrum-IPs kennzeichnen
`actionOn*`	string	Auszuführende Aktion: `log` (nur aufzeichnen), `require_mfa` (2FA erzwingen), `block` (Zugriff verweigern)
`maxTravelSpeedKmh`	integer	Geschwindigkeitsschwellenwert für die Erkennung unmöglicher Reisen (Standard: 900 km/h)

Erkennungskonfiguration aktualisieren

PATCH/api/suspicious-login/configRequires: manage:users

Die Erkennungskonfiguration für verdächtige Anmeldungen aktualisieren. Alle Felder sind optional. Änderungen wirken sich sofort auf nachfolgende Anmeldeversuche aus.

Anforderungs-Body


{
  "detectVpn": true,
  "actionOnVpn": "require_mfa",
  "actionOnImpossibleTravel": "block",
  "maxTravelSpeedKmh": 1000
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "detectNewDevice": true,
    "detectNewIp": true,
    "detectNewCountry": true,
    "detectImpossibleTravel": true,
    "detectVpn": true,
    "actionOnNewDevice": "log",
    "actionOnNewIp": "log",
    "actionOnNewCountry": "require_mfa",
    "actionOnImpossibleTravel": "block",
    "actionOnVpn": "require_mfa",
    "maxTravelSpeedKmh": 1000,
    "geoIpProvider": "ip-api",
    "updatedAt": "2025-02-18T11:30:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`VALIDATION_ERROR`	400	Ungültiger Aktionswert oder `maxTravelSpeedKmh` außerhalb des Bereichs (100-5000)

Das Setzen von actionOnImpossibleTravel oder actionOnNewCountry auf block kann legitime Benutzer aussperren, die häufig reisen oder mobile Netzwerke verwenden. Erwäge stattdessen require_mfa, das einen Verifizierungsschritt hinzufügt, ohne den Zugriff vollständig zu verweigern.

CAPTCHA

CAPTCHA-Verifizierung fügt den Authentifizierungsabläufen eine menschliche Herausforderung hinzu. Auris unterstützt drei Anbieter: Cloudflare Turnstile, hCaptcha und reCAPTCHA v3. CAPTCHA kann bei jedem Versuch, nur nach verdächtiger Aktivität oder nach einer konfigurierbaren Anzahl fehlgeschlagener Anmeldeversuche ausgelöst werden.

CAPTCHA-Konfiguration abrufen

GET/api/captcha/configRequires: manage:users

Die aktuelle CAPTCHA-Konfiguration für den Tenant abrufen.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "provider": "CLOUDFLARE_TURNSTILE",
    "trigger": "ON_SUSPICIOUS",
    "siteKey": "0x4AAAAAAA...",
    "scoreThreshold": 0.5,
    "enableOnLogin": true,
    "enableOnRegister": true,
    "enableOnReset": false,
    "updatedAt": "2025-02-15T10:00:00Z"
  }
}

Der secretKey wird niemals in API-Antworten zurückgegeben. Er kann nur über den Aktualisierungs-Endpunkt gesetzt werden.

CAPTCHA-Konfiguration aktualisieren

PATCH/api/captcha/configRequires: manage:users

Die CAPTCHA-Konfiguration aktualisieren. Alle Felder sind optional. Setze provider auf null, um CAPTCHA vollständig zu deaktivieren. siteKey und secretKey müssen für den ausgewählten Anbieter gültig sein.

Anforderungs-Body


{
  "provider": "CLOUDFLARE_TURNSTILE",
  "trigger": "AFTER_FAILURES",
  "siteKey": "0x4AAAAAAA_ihr_site_key",
  "secretKey": "0x4AAAAAAA_ihr_secret_key",
  "scoreThreshold": 0.5,
  "enableOnLogin": true,
  "enableOnRegister": true,
  "enableOnReset": true
}

Feld	Typ	Beschreibung
`provider`	string	`CLOUDFLARE_TURNSTILE`, `HCAPTCHA`, `RECAPTCHA_V3` oder `null` zum Deaktivieren
`trigger`	string	`ALWAYS` (bei jedem Versuch), `ON_SUSPICIOUS` (nach erkannter verdächtiger Aktivität), `AFTER_FAILURES` (nach N fehlgeschlagenen Anmeldungen)
`siteKey`	string	Öffentlicher Site-Key vom CAPTCHA-Anbieter
`secretKey`	string	Geheimschlüssel vom CAPTCHA-Anbieter (nur schreiben, wird nie zurückgegeben)
`scoreThreshold`	number	Score-Schwellenwert für reCAPTCHA v3 (0,0 - 1,0, Standard: 0,5). Für andere Anbieter ignoriert
`enableOnLogin`	boolean	CAPTCHA auf der Anmeldeseite aktivieren
`enableOnRegister`	boolean	CAPTCHA auf der Registrierungsseite aktivieren
`enableOnReset`	boolean	CAPTCHA auf der Passwort-Zurücksetzen-Seite aktivieren

Erfolgsantwort


{
  "ok": true,
  "data": {
    "provider": "CLOUDFLARE_TURNSTILE",
    "trigger": "AFTER_FAILURES",
    "siteKey": "0x4AAAAAAA_ihr_site_key",
    "scoreThreshold": 0.5,
    "enableOnLogin": true,
    "enableOnRegister": true,
    "enableOnReset": true,
    "updatedAt": "2025-02-18T12:00:00Z"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`VALIDATION_ERROR`	400	Ungültiger Anbieter, fehlender siteKey/secretKey wenn Anbieter gesetzt ist, oder scoreThreshold außerhalb des Bereichs

Kontosperrungen

Wenn ein Benutzer den in den Sicherheitseinstellungen konfigurierten lockoutThreshold überschreitet, wird sein Konto vorübergehend gesperrt. Administratoren können gesperrte Konten einsehen und manuell entsperren.

Gesperrte Konten auflisten

GET/api/admin/lockoutsRequires: manage:users

Alle aktuell gesperrten Benutzerkonten auflisten. Es werden nur Konten mit aktiven Sperrungen zurückgegeben. Natürlich abgelaufene Sperrungen sind nicht enthalten.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "lock_abc123",
        "userId": "usr_xyz789",
        "userEmail": "[email protected]",
        "userName": "Alice Smith",
        "failedAttempts": 5,
        "lockedAt": "2025-02-18T09:00:00Z",
        "expiresAt": "2025-02-18T09:15:00Z",
        "ipAddress": "203.0.113.50"
      },
      {
        "id": "lock_def456",
        "userId": "usr_abc123",
        "userEmail": "[email protected]",
        "userName": "Bob Jones",
        "failedAttempts": 5,
        "lockedAt": "2025-02-18T08:50:00Z",
        "expiresAt": "2025-02-18T09:05:00Z",
        "ipAddress": "198.51.100.42"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 2,
      "totalPages": 1
    }
  }
}

Konto entsperren

DELETE/api/admin/lockouts/[userId]Requires: manage:users

Ein Benutzerkonto sofort entsperren. Der Zähler für fehlgeschlagene Versuche wird auf null zurückgesetzt. Der Benutzer kann unmittelbar nach der Entsperrung wieder versuchen, sich anzumelden.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "unlocked": true,
    "userId": "usr_xyz789"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`NOT_FOUND`	404	Benutzer ist derzeit nicht gesperrt

Kontosperrungen laufen basierend auf der in den Sicherheitseinstellungen konfigurierten lockoutDuration automatisch ab. Manuelle Entsperrung ist nur erforderlich, wenn ein legitimer Benutzer gesperrt ist und nicht auf das Ablaufen der Sperrung warten kann.

Sicherheitsauswertungsreihenfolge

Bei jedem Authentifizierungsversuch wertet Auris Sicherheitsschichten in dieser Reihenfolge aus:

IP-Regeln — Wenn die Client-IP mit einer BLOCK-Regel übereinstimmt, wird die Anfrage sofort mit 403 IP_BLOCKED abgelehnt.
CAPTCHA — Wenn CAPTCHA konfiguriert ist und die Auslösebedingung erfüllt ist, muss der Client ein gültiges CAPTCHA-Token bereitstellen.
Rate Limiting — Gleitende Fenster-Rate-Limits werden geprüft (pro Stufe konfigurierbar).
Anmeldeinformationsvalidierung — Benutzername/Passwort oder andere Anmeldeinformationsverifizierung über Keycloak.
Brute Force / Sperrung — Zähler für fehlgeschlagene Versuche wird inkrementiert. Bei Erreichen des Schwellenwerts wird das Konto gesperrt.
Analyse verdächtiger Anmeldungen — Post-Authentifizierungsanalyse von Gerät, IP, Geografie und Reisemustern.
Adaptives MFA — Die Risikobewertung kann eine schrittweise Authentifizierung auslösen, wenn der Risikowert die Schwellenwerte überschreitet.

Jede Schicht ist unabhängig und kann deaktiviert werden, ohne die anderen zu beeinflussen.

Berechtigungsreferenz

Berechtigung	Beschreibung
`manage:users`	IP-Regeln verwalten, verdächtige Anmeldeereignisse überprüfen, CAPTCHA konfigurieren und Konten entsperren

Sicherheitsverwaltungsoperationen sind unter der Berechtigung manage:users gruppiert. Dies stellt sicher, dass nur Administratoren mit vollem Benutzerverwaltungszugriff Sicherheitseinstellungen ändern können, die die Authentifizierung aller Benutzer im Tenant betreffen.

Sicherheits-API

IP-Regeln

IP-Regeln auflisten

IP-Regel erstellen

IP-Regel aktualisieren

IP-Regel löschen

Verdächtige Anmeldeereignisse

Verdächtige Anmeldeereignisse auflisten

Ereignis als überprüft markieren

Erkennungskonfiguration abrufen

Erkennungskonfiguration aktualisieren

CAPTCHA

CAPTCHA-Konfiguration abrufen

CAPTCHA-Konfiguration aktualisieren

Kontosperrungen

Gesperrte Konten auflisten

Konto entsperren

Sicherheitsauswertungsreihenfolge

Berechtigungsreferenz

Verwandte Themen