Vai al contenuto

Autenticazione a due fattori ​

Pocket Alert supporta l'autenticazione a due fattori TOTP sia sulla dashboard web sia sull'app mobile. Una volta attivata, la sola password non basta più per accedere al tuo account.

Configurala da Account → Sicurezza.

Come configurarla ​

  1. Apri Account → Sicurezza e avvia la configurazione. Ottieni un codice QR e un segreto.
  2. Scansionalo con un qualsiasi authenticator TOTP — Google Authenticator, 1Password, Authy, Bitwarden.
  3. Inserisci il codice a sei cifre per confermare. Solo dopo un codice corretto l'autenticazione a due fattori si attiva davvero.
  4. Salva i codici di recupero che ti vengono mostrati. Ognuno funziona una sola volta.

La configurazione interrotta è sicura

Avviare una nuova configurazione non tocca la tua autenticazione a due fattori attuale. Il nuovo segreto finisce in uno slot in attesa e sostituisce quello attivo solo dopo che confermi un codice, quindi chiudere la scheda a metà non ti blocca fuori dall'account.

Come cambia il login ​

Con l'autenticazione a due fattori attiva, POST /v1/auth/login non restituisce più un JWT. Restituisce una sfida a breve durata:

json
{
  "two_factor_required": true,
  "challenge": "eyJhbGciOiJIUzI1NiIs…"
}

Scambia la sfida insieme a un codice con il token vero:

POST https://api.pocketalert.app/v1/auth/2fa/login
bash
curl -X POST "https://api.pocketalert.app/v1/auth/2fa/login" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge": "eyJhbGciOiJIUzI1NiIs…",
    "code": "482913"
  }'

Uno scambio riuscito restituisce lo stesso payload di un login normale — token, name, email, avatar. Il campo code accetta sia un codice TOTP a sei cifre sia uno dei tuoi codici di recupero.

Le sfide restano valide per 5 minuti.

Le chiavi API non sono interessate ​

Gli script continuano a funzionare

L'autenticazione a due fattori si applica ai login interattivi. Le chiavi API di Chiavi API si autenticano con l'header Token e non ricevono alcuna sfida — i tuoi cron job, le pipeline CI e gli hook di monitoraggio continuano a inviare avvisi esattamente come prima.

Per questo conviene anche assegnare le chiavi API per singolo servizio: revocarne una non interferisce con le altre.

Codici di recupero ​

I codici di recupero sono monouso e vengono consumati in modo atomico — due login paralleli non possono usare lo stesso codice. Puoi generarne un nuovo set in qualsiasi momento da Account → Sicurezza; emettere nuovi codici invalida quelli vecchi.

Hai perso sia l'authenticator sia i codici? Contatta il supporto. Non esiste un bypass self-service, ed è proprio questo lo scopo.

Protezione da attacchi brute-force ​

Cinque codici errati bloccano l'account per 15 minuti, e i tentativi successivi restituiscono 429. Il contatore si azzera a un login riuscito e quando attivi o disattivi l'autenticazione a due fattori. Poiché una sfida resta valida per i suoi cinque minuti interi, è questo limite di tentativi — non la durata della sfida — a rendere impraticabile l'indovinare un codice a sei cifre.

Notifiche email ​

Ricevi un'email ogni volta che l'autenticazione a due fattori viene attivata o disattivata sul tuo account. Se ne arriva una e non sei stato tu, è il segnale per cambiare subito la password.

Endpoint ​

MetodoEndpointScopo
GET/v1/auth/2fa/statusIndica se l'autenticazione a due fattori è attiva e quanti codici di recupero restano
POST/v1/auth/2fa/setupAvvia la registrazione — restituisce il segreto e il payload del QR
POST/v1/auth/2fa/enableConferma un codice e attiva l'autenticazione a due fattori
POST/v1/auth/2fa/disableDisattiva l'autenticazione a due fattori — richiede un codice e la tua password
POST/v1/auth/2fa/recovery-codesEmette un nuovo set di codici di recupero
POST/v1/auth/2fa/loginScambia sfida + codice con un JWT (nessun header di autenticazione)

Ogni endpoint tranne /auth/2fa/login richiede una sessione autenticata.

Correlati ​

  • Login — il primo passo del flusso di login
  • Introduzione — panoramica sull'autenticazione

Documentazione di Pocket Alert