> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticazione e Controllo degli Accessi

> Gestione delle sessioni, RBAC, ciclo di vita delle API key, politica delle password e MFA per i workspace Switchbord.

## Integrazione con Supabase Auth

Switchbord utilizza Supabase Auth come spina dorsale dell'autenticazione. Tutte le sessioni utente sono gestite tramite il sistema di sessione basato su JWT di Supabase, con validazione lato server a ogni richiesta API.

<Note>
  L'autenticazione è applicata a livello di route API. Ogni route inizia con la validazione della sessione prima che venga eseguita qualsiasi logica di business.
</Note>

## Gestione delle Sessioni

### Timebox delle Sessioni

Le sessioni sono soggette a due controlli di scadenza indipendenti:

| Controllo             | Valore | Descrizione                                               |
| --------------------- | ------ | --------------------------------------------------------- |
| Timeout assoluto      | 8 ore  | La sessione scade dopo 8h indipendentemente dall'attività |
| Timeout di inattività | 1 ora  | La sessione scade se non c'è attività per 1h              |

Questi limiti sono configurati in Supabase e applicati lato server — estenderli richiede una modifica della configurazione da parte di un admin, non un workaround lato client.

### Revoca della Sessione alla Rimozione di un Membro

Quando un membro del workspace viene rimosso, le sue sessioni attive vengono immediatamente invalidate su tutti i dispositivi:

```typescript theme={null}
// Chiamata durante la rimozione di un membro del workspace
await supabaseAdmin.auth.admin.signOut(userId, 'global');
```

L'ambito `'global'` garantisce che tutte le sessioni dell'utente vengano terminate — non solo quella corrente. Ciò impedisce a un membro rimosso di continuare a utilizzare una sessione esistente dopo aver perso l'accesso al workspace.

## Politica delle Password

Switchbord applica i seguenti requisiti per le password, configurati in Supabase:

* Minimo **12 caratteri**
* Almeno una **lettera maiuscola**
* Almeno una **cifra**
* Applicata alla registrazione e al cambio password

<Tip>
  Si incoraggia gli utenti a utilizzare un password manager e a generare password univoche per ogni servizio.
</Tip>

## Autenticazione Multi-Fattore

L'MFA TOTP (Time-based One-Time Password) di Supabase è disponibile per tutti gli utenti. Gli utenti possono registrare un'app di autenticazione dalle impostazioni del proprio account.

<Warning>
  L'**applicazione obbligatoria** dell'MFA (richiedere l'MFA per tutti i membri del workspace) è attualmente **pianificata** e tracciata nella roadmap. Finché l'applicazione obbligatoria non sarà implementata, l'MFA è opzionale per singolo utente. Le organizzazioni con requisiti di conformità rigorosi dovrebbero istruire i propri membri a registrarsi.
</Warning>

## Controllo degli Accessi Basato sui Ruoli

Switchbord implementa quattro ruoli con livelli di permesso distinti. L'assegnazione dei ruoli è gestita dagli owner e dagli admin del workspace.

### Gerarchia dei Ruoli

| Ruolo         | Descrizione                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------ |
| **owner**     | Controllo completo del workspace inclusi fatturazione, eliminazione e trasferimento di proprietà |
| **admin**     | Controllo operativo completo inclusa la gestione dei membri e tutte le impostazioni              |
| **developer** | Accesso API, configurazione delle integrazioni, impostazioni tecniche                            |
| **operator**  | Operazioni quotidiane: conversazioni, contatti, invio di messaggi                                |

### Applicazione dei Ruoli

I controlli sui ruoli vengono eseguiti a ogni route API dopo la risoluzione del contesto del workspace:

```typescript theme={null}
export async function DELETE(req: NextRequest) {
  // Primo passo: stabilire workspace e ruolo dall'utente autenticato
  const { workspaceId, role } = await requireSettingsAccess(req, ['owner', 'admin']);
  // Solo owner e admin arrivano a questo punto
  // ...
}
```

L'elenco dei ruoli passato a `requireSettingsAccess` definisce i ruoli minimi richiesti. Le route non presenti nell'elenco riceveranno una risposta 403.

### Riferimento delle Capacità per Ruolo

| Capacità                       | operator | developer | admin | owner |
| ------------------------------ | -------- | --------- | ----- | ----- |
| Visualizzare le conversazioni  | ✅        | ✅         | ✅     | ✅     |
| Inviare messaggi               | ✅        | ✅         | ✅     | ✅     |
| Gestire i contatti             | ✅        | ✅         | ✅     | ✅     |
| Configurare le integrazioni    | ❌        | ✅         | ✅     | ✅     |
| Gestire le API key             | ❌        | ✅         | ✅     | ✅     |
| Gestire i membri del workspace | ❌        | ❌         | ✅     | ✅     |
| Configurare i provider AI      | ❌        | ✅         | ✅     | ✅     |
| Accedere ai log di audit       | ❌        | ❌         | ✅     | ✅     |
| Eliminare il workspace         | ❌        | ❌         | ❌     | ✅     |

## Gestione delle API Key

### Ciclo di Vita delle Chiavi

Le API key consentono l'accesso programmatico all'API di Switchbord. Ogni chiave viene:

1. **Generata** con un valore crittograficamente casuale
2. **Sottoposta a hashing** con SHA-256 prima della memorizzazione — il testo in chiaro viene mostrato una sola volta al momento della creazione
3. **Ambita** al workspace che la crea — non può essere utilizzata per accedere ad altri workspace
4. **Opzionalmente scaduta** — `expires_at` viene applicato al momento della validazione

```typescript theme={null}
// Creazione della chiave — hashing prima della memorizzazione
const rawKey = generateSecureToken();
const hashedKey = sha256(rawKey);
const keyPrefix = rawKey.slice(0, 8); // memorizzato per l'identificazione visuale

await db.insert(apiKeys).values({
  workspaceId,
  hashedKey,
  prefix: keyPrefix,
  expiresAt: options.expiresAt ?? null,
  createdBy: userId,
});

// Restituisce la chiave in chiaro una sola volta — non viene mai più memorizzata
return { key: rawKey, prefix: keyPrefix };
```

### Confronto Timing-Safe

La validazione delle API key utilizza `crypto.timingSafeEqual` per prevenire attacchi timing side-channel:

```typescript theme={null}
import { timingSafeEqual } from 'crypto';

function validateApiKey(providedKey: string, storedHash: string): boolean {
  const providedHash = sha256(providedKey);
  const a = Buffer.from(providedHash, 'hex');
  const b = Buffer.from(storedHash, 'hex');

  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}
```

### Applicazione della Scadenza delle Chiavi

Le chiavi con un valore `expires_at` vengono rifiutate al momento della validazione, anche se l'hash corrisponde:

```typescript theme={null}
if (key.expiresAt && key.expiresAt < new Date()) {
  throw new UnauthorizedError('API key has expired');
}
```

### Operazioni sulle Chiavi con Ambito Workspace

Tutte le operazioni sulle chiavi (elenco, eliminazione, revoca) sono filtrate in base al workspace risolto del chiamante:

```typescript theme={null}
// Un developer nel workspace A non può eliminare le chiavi del workspace B
await db.delete(apiKeys)
  .where(
    and(
      eq(apiKeys.id, keyId),
      eq(apiKeys.workspaceId, workspaceId) // derivato dall'autenticazione, non dal corpo della richiesta
    )
  );
```

## Mappatura della Conformità

| Standard  | Controllo                                                     | Implementazione                                                                  |
| --------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| ISO 27001 | A.9.2 — Gestione degli accessi degli utenti                   | Modello solo su invito, provisioning basato sui ruoli                            |
| ISO 27001 | A.9.3 — Responsabilità degli utenti                           | Politica delle password applicata a livello di piattaforma                       |
| ISO 27001 | A.9.4 — Controllo dell'accesso al sistema e alle applicazioni | RBAC su ogni route API                                                           |
| ISO 27001 | A.9.4.3 — Sistema di gestione delle password                  | Minimo 12 caratteri, maiuscola + cifra richiesti                                 |
| HIPAA     | §164.312(d) — Autenticazione della persona o dell'entità      | Validazione della sessione + autenticazione tramite API key su tutte le route    |
| HIPAA     | §164.312(a)(1) — Controllo degli accessi                      | RBAC con assegnazioni di ruolo a privilegio minimo                               |
| SOC 2     | CC6.1 — Controlli di accesso logico                           | RBAC con ambito workspace applicato lato server                                  |
| SOC 2     | CC6.2 — Gestione delle credenziali di sistema                 | Hashing delle API key, visualizzazione del prefisso, applicazione della scadenza |
| SOC 2     | CC6.3 — Accesso basato sui ruoli                              | Gerarchia a quattro ruoli applicata su tutte le route                            |

<Tip>
  Per la mappatura completa dei controlli di conformità, vedi la [Matrice di Conformità](/it/security/compliance-matrix).
</Tip>