Waterstream 1.7.0 verifica i JWT tramite un endpoint JWKS, con una scorciatoia in una riga per Azure Entra ID. L’autenticazione avanzata MQTT v5 (Enhanced Authentication) permette a una sessione di lunga durata di rinnovare i token senza disconnettersi.
Prima della versione 1.7.0, configurare l’autenticazione JWT significava fissare una singola chiave di firma nella configurazione del broker. Funziona con un IdP che ruota raramente. Non funziona con Azure Entra ID, che ruota le chiavi JWKS secondo il proprio calendario. Qualsiasi token firmato con un kid che il broker non conosce viene rifiutato. La versione 1.7.0 colma questa lacuna: il broker recupera le chiavi a runtime e le aggiorna quando compare un kidsconosciuto.
Il flusso JWKS generico
Cinque nuove variabili d’ambiente espongono il percorso JWKS:
JWT_JWKS_URL: l’URL del documento JWKSJWT_EXPECTED_ISSUER: il valore che il claimissdeve corrispondereJWT_PRINCIPAL_CLAIM: quale claim diventa{username}nelle regole ACL (predefinito:sub)JWT_ORGANIZATION_CLAIM: quale claim popola{organization}JWT_ENTRA_ID_TENANT_ID: la scorciatoia per Entra ID (vedi sotto)
Una configurazione OIDC generica si presenta così:
La cache è indicizzata per kid. Un intervallo minimo di 60 secondi tra gli aggiornamenti impedisce che un’ondata di token non validi sovraccarichi l’IdP. Le opzioni per chiavi statiche (JWT_VERIFICATION_KEY, JWT_VERIFICATION_KEY_BASE64, JWT_VERIFICATION_KEY_PATH) continuano a funzionare per i setup che non richiedono rotazione, ma il broker si rifiuta di avviarsi se le si combina con JWT_JWKS_URL
La scorciatoia per Entra ID
Se il tuo IdP è Azure Entra ID, è sufficiente impostare il tenant ID:
JWT_JWKS_URL e JWT_EXPECTED_ISSUER vengono derivati dal tenant ID:
| Setting | Valore derivato |
|---|---|
JWT_JWKS_URL | https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys |
JWT_EXPECTED_ISSUER | https://login.microsoftonline.com/<tenant-id>/v2.0 |
Se è necessario sovrascrivere uno dei due (un cloud Azure sovrano, un’app multi-tenant), le variabili d’ambiente esplicite hanno la precedenza.
I token di accesso di Entra ID riportano il GUID dell’app senza prefisso nel claim aud, non l’URI completo api://<guid>. Imposta JWT_AUDIENCE sul GUID, altrimenti la validazione del token fallirà pur avendo in mano un token apparentemente valido.
Claim mappati all’ ACL placeholder
Gli stessi claim che autenticano il client guidano anche l’autorizzazione. Le nuove variabili espongono tre segnaposto per il motore ACL:
| JWT claim | Config | ACL placeholder |
|---|---|---|
oid (Entra) / sub (generic) | JWT_PRINCIPAL_CLAIM | {username} |
azp / appid (Entra) | JWT_ORGANIZATION_CLAIM | {organization} |
roles (Entra) / groups (generic) | JWT_GROUPS_CLAIM_NAME | {group} |
Una regola come t/{organization}/{username}/# limita automaticamente un client a un prefisso topic costruito dall’app chiamante e dal suo object ID stabile, senza necessità di livelli di mapping aggiuntivi
Rinnovo dei token senza interrompere la sessione
I token di Entra ID hanno una durata di circa un’ora. Se i tuoi client MQTT si riconnettono ogni ora per rinnovare i token, perdi tutto lo stato della sessione che non era stato persistito e devi pagare il costo di una nuova sottoscrizione a ogni topic attivo. Per sessioni di lunga durata su dispositivi con risorse limitate, il costo è elevato.
MQTT v5 ha una soluzione: Enhanced Authentication. Il token viaggia nelle proprietà Authentication Method e Authentication Datadel pacchetto CONNECT, invece che in User Name e Password.. Waterstream 1.7 la supporta, con JWT come unico metodo attualmente registrato:
Il flusso legacyUser Name = JWT / Password = <token> funziona ancora ed è l’unica opzione per i client MQTT 3.1.1.
La ri-autenticazione in sessione è il punto centrale. Un client v5 che si è connesso con Enhanced Authentication può inviare un pacchetto AUTH in qualsiasi momento con un token aggiornato. Waterstream valida il nuovo token, conferma il pacchetto e la sessione prosegue senza interruzioni, con il timer di scadenza aggiornato all’expdel nuovo token. Le sottoscrizioni rimangono attive. I messaggi QoS 1 e 2 in transito non vanno persi. La connessione TCP non viene toccata.
Attiva la ri-autenticazione al 75–80% della durata del token corrente, in modo che il rinnovo avvenga prima che il broker verifichi nuovamente la scadenza. Se una ri-autenticazione fallisce, il broker disconnette la sessione e include una proprietà Reason String utile da registrare sul lato client.
Ulteriori informazioni
Il riferimento completo alla configurazione si trova nella sezione Autenticazione della guida alla configurazione, con esempi pratici per il flusso JWKS generico e per Entra ID. La sezione MQTT v5 Enhanced Authentication include snippet per i client Eclipse Paho e HiveMQ relativi ai flussi CONNECT e reauth.
Waterstream 1.7.0 è disponibile ora. Richiedi una licenza di sviluppo e configura il broker con il tuo tenant Entra ID, oppure contatta un architect se preferisci rivedere insieme il flusso di autenticazione.