API Sicurezza

L’API Sicurezza fornisce strumenti per proteggere il tenant da accessi non autorizzati e attività malevole. Gli amministratori possono gestire liste di IP consentiti/bloccati, esaminare eventi di login sospetti, configurare la verifica CAPTCHA e gestire i blocchi degli account.

Auris valuta le regole di sicurezza durante ogni tentativo di autenticazione in questo ordine: regole IP (blocco/permesso) → verifica CAPTCHA → rate limiting → validazione credenziali → analisi login sospetti → MFA adattivo. Ogni livello opera indipendentemente e può essere configurato separatamente.

Regole IP

Le regole IP definiscono liste di permesso e blocco usando la notazione CIDR. Le regole di blocco hanno sempre precedenza sulle regole di permesso. Le regole possono essere limitate all’intero tenant o a un’applicazione specifica.

Elenca Regole IP

Parametri di query

Risposta di successo

{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "ipr_abc123",
        "cidr": "203.0.113.0/24",
        "type": "BLOCK",
        "scope": "TENANT",
        "applicationId": null,
        "label": "Known bad actor range",
        "note": "Blocked after brute-force campaign on 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": "Corporate VPN",
        "note": "Internal network range",
        "isTemporary": false,
        "expiresAt": null,
        "isActive": true,
        "createdAt": "2025-01-15T09:00:00Z",
        "updatedAt": "2025-01-15T09:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
  }
}

Crea Regola IP

Corpo della richiesta

{
  "cidr": "192.0.2.0/24",
  "type": "BLOCK",
  "scope": "TENANT",
  "label": "Datacenter range",
  "note": "Blocked due to automated scraping activity",
  "isTemporary": true,
  "expiresAt": "2025-04-01T00:00:00Z"
}

Codici di errore

Aggiorna Regola IP

Elimina Regola IP

Codici di errore

Eventi di Login Sospetti

Auris monitora i tentativi di login per comportamenti anomali usando cinque metodi di rilevamento: nuovo dispositivo, nuovo indirizzo IP, nuovo paese, viaggio impossibile e utilizzo VPN/proxy. Quando viene rilevata un’attività sospetta, viene registrato un evento e viene eseguita l’azione configurata (solo log, richiesta MFA, o blocco).

Elenca Eventi di Login Sospetti

Parametri di query

Risposta di successo

{
  "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" },
          "currentLocation": { "country": "Brazil", "city": "Sao Paulo" },
          "distanceKm": 9187,
          "timeDiffMinutes": 45,
          "requiredSpeedKmh": 12249
        },
        "ipAddress": "198.51.100.42",
        "reviewed": false,
        "createdAt": "2025-02-18T09:15:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 47, "totalPages": 3 }
  }
}

Segna Evento come Revisionato

Codici di errore

Recupera Configurazione Rilevamento

Risposta di successo

{
  "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"
  }
}

Aggiorna Configurazione Rilevamento

CAPTCHA

La verifica CAPTCHA aggiunge una sfida umana ai flussi di autenticazione. Auris supporta tre provider: Cloudflare Turnstile, hCaptcha e reCAPTCHA v3. Il CAPTCHA può essere attivato ad ogni tentativo, solo dopo attività sospetta, o dopo un numero configurabile di tentativi di login falliti.

Recupera Configurazione CAPTCHA

Risposta di successo

{
  "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"
  }
}

Aggiorna Configurazione CAPTCHA

Corpo della richiesta

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

Codici di errore

Blocchi Account

Quando un utente supera il lockoutThreshold configurato nelle impostazioni di sicurezza, il suo account viene temporaneamente bloccato. Gli amministratori possono visualizzare gli account bloccati e sbloccarli manualmente.

Elenca Account Bloccati

Risposta di successo

{
  "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"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
  }
}

Sblocca Account

Risposta di successo

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

Codici di errore

Ordine di Valutazione della Sicurezza

Durante ogni tentativo di autenticazione, Auris valuta i livelli di sicurezza in questo ordine:

1. Regole IP — Se l’IP del client corrisponde a una regola BLOCK, la richiesta viene negata con 403 IP_BLOCKED.
2. CAPTCHA — Se il CAPTCHA è configurato e la condizione di trigger è soddisfatta, il client deve fornire un token CAPTCHA valido.
3. Rate Limiting — Vengono controllati i limiti di frequenza a finestra scorrevole (configurabili per tier).
4. Validazione Credenziali — Verifica nome utente/password o altre credenziali tramite Keycloak.
5. Brute Force / Blocco — Il contatore dei tentativi falliti viene incrementato. Se la soglia viene raggiunta, l’account viene bloccato.
6. Analisi Login Sospetti — Analisi post-autenticazione di dispositivo, IP, geografia e pattern di viaggio.
7. MFA Adattivo — La valutazione del rischio può richiedere un’autenticazione step-up se il punteggio di rischio supera le soglie.

Ogni livello è indipendente e può essere disabilitato senza influenzare gli altri.

Riferimento Permessi

Correlati

• MFA Adattivo e Risk Scoring — Come la valutazione del rischio guida le decisioni di sicurezza
• Protezione dagli Attacchi — Configura protezione brute-force e login sospetti
• Configurazione Protezione Minacce — Regole IP, CAPTCHA e rilevamento bot
• Impostazioni di Sicurezza — Gestisci tutte le funzionalità di sicurezza dalla Console