Autenticazione

Questa sezione spiega come funzionano autenticazione e autorizzazione in Homsai Backend v2: token JWT, modello di permessi e convenzioni di sicurezza sugli endpoint.

---

Overview

Questa sezione descrive:

• come ottenere e utilizzare i token JWT per autenticare le richieste;

• come funziona il modello di autorizzazione basato su permessi e proprietà del plant;

• quali sono le regole di sicurezza generalmente applicate agli endpoint;

• alcuni esempi pratici di chiamate tipiche.

• Autenticazione JWT

  • Tipi di token
  • Flusso di login

• Modello di autorizzazione

  • Permessi
  • Controllo proprietà (ownership)

• Convenzioni di sicurezza sugli endpoint

• Esempi pratici

---

JWT Autenticazione

Tipi di Token

Il flusso di autenticazione utilizza due tipi di token:

• accessToken
  • A breve durata.
  • Inviato in ogni chiamata protetta nell’header Authorization.
• refreshToken
  • A durata più lunga.
  • Utilizzato per ottenere un nuovo access token senza ripetere il login con credenziali.

Entrambi i token vengono emessi dall’endpoint POST /auth/login.

Fluso di Login

1. Il client invia una richiesta POST /auth/login con le credenziali utente nel body JSON.
2. Il backend valida le credenziali e restituisce un accessToken e un refreshToken.
3. Il client memorizza i token in modo sicuro e utilizza l’accessToken per le chiamate successive.

Esempio di header per qualsiasi richiesta protetta:

Authorization: Bearer <accessToken>

Quando l'accessToken scade, il client può chiamare GET /auth/token passando il refreshToken (secondo lo schema documentato) per ricevere un nuovo access token.

---

Modello di autorizzazione

Permessi

Ogni area funzionale è protetta da specifici permessi. Ecco alcuni esempi tipici:

Impianti

• PLANTS READ
• PLANTS CREATE
• PLANTS UPDATE
• PLANTS DELETE

Dispositivi

• DEVICES READ
• DEVICES CREATE
• DEVICES UPDATE
• DEVICES DELETE

Sensori

• SENSORS READ
• SENSORS CREATE
• SENSORS UPDATE
• SENSORS DELETE

Tipi e firme

• SENSOR_TYPES READ/CREATE/UPDATE/DELETE
• DEVICE_TYPES READ/CREATE/UPDATE/DELETE
• LOAD_SIGNATURES READ/CREATE/UPDATE/DELETE

Energia e metriche

• PLANT_POWER_CONSUMPTION READ
• PLANT_POWER_PRODUCTION READ
• DAILY_PREDICTIONS READ
• ENERGY_TYPE READ
• PLANT_HEALTH READ

Il set esatto di permessi associato a un utente dipende dai ruoli configurati nel backend di Homsai.

Controlli di proprietà

Per molte operazioni su un determinato impianto (e sui suoi dispositivi o sensori), il backend applica controlli di proprietà:

• il chiamante deve avere il permesso richiesto (es. PLANTS UPDATE)
• e deve essere il proprietario della risorsa (impianto)

Se un utente ha il permesso generico ma non è proprietario dell'impianto, il backend restituirà 403 Forbidden.

Convenzioni di sicurezza per gli endpoint

Tutte le operazioni di lettura o scrittura su impianti, dispositivi, sensori, metriche e previsioni richiedono:

• un JWT accessToken valido
• i permessi appropriati
• e, dove applicabile, la proprietà dell'impianto

Endpoint di autenticazione pubblici:

• POST /auth/login
• POST /auth/resetPassword

Endpoint di configurazione speciali:

• POST /auth/setPassword

Errori:

• Token mancante/non valido → 401 Unauthorized
• Token valido ma permessi/ownership mancanti → 403 Forbidden