Skip to content

Gestione delle password

Configura in Potato l'hashing PBKDF2-SHA256, il reset da CLI o API di amministrazione, il reset self-service con token e l'archiviazione delle credenziali su SQLite o PostgreSQL.

Novità della v2.4.0

Il sistema di autenticazione di Potato usa PBKDF2-SHA256 con 100.000 iterazioni e un salt per ogni utente, l'approccio raccomandato dal NIST per l'archiviazione sicura delle password. Questa pagina spiega come vengono conservate le password, come reimpostarle e come far sopravvivere le credenziali ai riavvii del server.

Implementazione della sicurezza

Le password sono conservate nel formato salt$hash:

  • salt esadecimale di 32 caratteri, diverso per ogni utente
  • hash SHA-256 di 64 caratteri calcolato su salt + password
  • confronto a tempo costante tramite hmac.compare_digest per prevenire gli attacchi temporali

Le password in chiaro già presenti nei file user_config.jsonl vengono ricalcolate in automatico come hash con salt univoci quando Potato le carica: non serve alcuna migrazione manuale.

Configurazione predefinita

Per impostazione predefinita Potato usa l'autenticazione in memoria. Gli annotatori devono essere elencati nella configurazione:

yaml
authentication:
  method: in_memory
  require_password: true
 
user_config:
  users:
    - username: "annotator1"
      password: "initial-password"   # will be hashed on first load
    - username: "annotator2"
      password: "initial-password"

Credenziali persistenti

Le credenziali in memoria si perdono al riavvio. Per conservarle, usa un backend su file o su database.

Persistenza su file

yaml
authentication:
  method: in_memory
  user_config_path: /shared/path/to/user_config.jsonl

Potato scrive in questo file le credenziali in forma di hash e le rilegge al riavvio: le password impostate o cambiate durante una sessione sopravvivono ai riavvii.

Backend su database

SQLite (nessuna dipendenza aggiuntiva):

yaml
authentication:
  method: database
  database_url: "sqlite:///auth/users.db"

PostgreSQL (richiede psycopg2-binary):

yaml
authentication:
  method: database
  database_url: "postgresql://user:password@localhost:5432/potato_auth"

Le tabelle del database vengono create in automatico al primo avvio.

Nota: method: database e user_config_path si escludono a vicenda, scegli una sola strategia di persistenza.

Reimpostare le password

CLI di amministrazione

Reimposta una password dalla riga di comando:

bash
# Reset a specific user's password
potato reset-password config.yaml --username annotator1
 
# Prompted for new password interactively

API di amministrazione

Reimposta la password via codice con una chiave API:

bash
curl -X POST http://localhost:8000/admin/reset_password \
  -H "X-API-Key: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "annotator1", "new_password": "new-secure-password"}'

Reset self-service con token

Potato supporta un flusso di reset avviato dall'utente. L'utente va su /forgot-password, inserisce il proprio nome utente e riceve un token di reset monouso. Poi visita /reset/<token> per impostare una nuova password.

I token restano validi 24 ore e si possono usare una volta sola. Potato non invia email: è l'amministratore a distribuire il link di reset.

Abilitazione nella configurazione:

yaml
authentication:
  method: database
  database_url: "sqlite:///auth/users.db"
  allow_password_reset: true
  reset_token_ttl_hours: 24

Flusso lato amministratore:

bash
# Generate a reset token for a user
curl -X POST http://localhost:8000/admin/generate_reset_token \
  -H "X-API-Key: $ADMIN_API_KEY" \
  -d '{"username": "annotator1"}'
 
# Returns: {"reset_url": "https://your-server.com/reset/abc123..."}
# Share this URL with the annotator

Modalità senza password

Per le dimostrazioni in aula, gli studi rapidi o i compiti che usano un'autenticazione esterna (MTurk, Prolific), puoi disattivare del tutto le password:

yaml
authentication:
  method: in_memory
  require_password: false

Gli annotatori entrano indicando un nome utente qualsiasi, senza che compaia la richiesta della password. Sconsigliato per dati sensibili o per compiti in cui l'identità va verificata.

Vedi Accesso Senza Password per i dettagli.

Riferimento completo

yaml
authentication:
  method: in_memory       # in_memory | database | oauth | clerk
 
  # In-memory options
  require_password: true
  user_config_path: path/to/users.jsonl   # optional persistence
 
  # Database options (mutually exclusive with user_config_path)
  database_url: "sqlite:///auth/users.db"
 
  # Self-service reset
  allow_password_reset: true
  reset_token_ttl_hours: 24
 
user_config:
  users:
    - username: "researcher"
      password: "secure-passphrase"
      role: admin
    - username: "annotator1"
      password: "initial-pass"
      role: annotator

Ulteriori letture

Per i dettagli implementativi, vedi la documentazione sorgente.