Licenze Software

La maggior parte dei prodotti software ha bisogno di un modo per controllare chi può utilizzarli e a quali condizioni. Che si tratti di un’applicazione desktop, un server on-premise, uno strumento CLI o un SDK, è necessario rispondere a domande come: “Questo utente ha pagato?”, “Quante postazioni sono consentite?”, “Questa licenza è ancora valida?” e “Questo dispositivo può eseguire il software?”

Auris Licensing fornisce un sistema completo per emettere, validare e gestire chiavi di licenza software. È integrato nella piattaforma Auris insieme all’autenticazione e all’autorizzazione, così da poter collegare le licenze direttamente ai propri utenti, organizzazioni e tenant esistenti.

Il modello di licenza

Auris Licensing è organizzato attorno a tre concetti fondamentali: Policy, Chiavi e Diritti (Entitlement). Formano una gerarchia che separa il modello (che tipo di licenza) dall’istanza (una licenza specifica rilasciata a un cliente specifico) dalle concessioni (cosa la licenza effettivamente consente).

Policy

Una policy è un modello che definisce le regole e la struttura di una classe di licenze. Le policy vengono create prima di emettere qualsiasi chiave. Un singolo prodotto potrebbe avere diverse policy — una per il periodo di prova, una per il piano personale, una per il piano enterprise.

Una policy definisce:

Le policy sono immutabili per progettazione. Quando è necessario modificare le condizioni per nuovi clienti, si crea una nuova versione della policy. Le chiavi esistenti emesse con la policy precedente mantengono le condizioni originali, a meno che non vengano migrate esplicitamente.

Chiavi

Una chiave è un’istanza specifica di licenza emessa in base a una policy e assegnata a un licenziatario. Il licenziatario può essere un utente, un’organizzazione o un dispositivo — a seconda del modello di licenza.

Quando una chiave viene creata, Auris:

1. Genera la stringa della chiave secondo il formato definito nella policy
2. Registra l’associazione tra la chiave, la policy e il licenziatario
3. Calcola i diritti iniziali in base ai valori predefiniti della policy
4. Imposta la data di scadenza (se la policy ha una durata)
5. Emette un evento license.key.created (per webhook e automazione)

Le chiavi hanno un ciclo di vita:

Created → Active → [Suspended] → [Expired | Revoked]

• Active: La chiave supera i controlli di validazione e il licenziatario può utilizzare il software.
• Suspended: Temporaneamente disabilitata (es. pagamento non riuscito). Può essere riattivata.
• Expired: Il periodo di validità della chiave è terminato. Non può essere riattivata senza emettere una nuova chiave o estendere la scadenza.
• Revoked: Invalidata permanentemente da un amministratore. Non può essere riattivata.

Diritti (Entitlement)

I diritti sono ciò che la chiave effettivamente concede a runtime. Sono i permessi e i limiti concreti che l’applicazione verifica.

I diritti includono:

• Feature flag: Valori booleani con nome (es. advanced-analytics, custom-branding, api-access)
• Conteggio postazioni: Quanti utenti possono utilizzare il software contemporaneamente o in totale
• Conteggio dispositivi: Su quante macchine la chiave può essere attivata
• Data di scadenza: Quando i diritti scadono
• Metadati: Coppie chiave-valore arbitrarie per logica di licenza personalizzata

Sebbene i diritti vengano inizialmente derivati dalla policy, possono essere sovrascritti per singola chiave. Questo consente di gestire eccezioni senza creare una nuova policy — ad esempio, concedere 5 postazioni aggiuntive a un cliente specifico come parte di un accordo negoziato.

Modalità di validazione

Quando l’applicazione deve verificare se una licenza è valida, esegue un controllo di validazione. Auris supporta tre modalità di validazione, ciascuna con compromessi diversi tra sicurezza, disponibilità e latenza.

Validazione Online

Ogni controllo di validazione effettua una chiamata API ad Auris:

Client → POST /api/licensing/validate → Auris API → Database → Response

L’API verifica che la chiave esista, sia attiva, non sia scaduta e che il dispositivo/utente corrente rientri nei limiti consentiti. La risposta include l’oggetto completo dei diritti.

Punti di forza: Sempre aggiornata. Le revoche hanno effetto immediato. Il conteggio di postazioni e dispositivi è accurato in tempo reale.

Punti deboli: Richiede connettività di rete. Aggiunge latenza a ogni controllo. Se Auris non è raggiungibile, l’applicazione non può validare.

Ideale per: Applicazioni SaaS, web app e qualsiasi ambiente con connettività internet affidabile.

Validazione Ibrida

Prima online, con fallback su JWT firmato per scenari offline:

Client → POST /api/licensing/validate → Successo? Usa la risposta
                                       → Errore/timeout? Usa il JWT in cache

Quando una validazione online ha successo, l’API restituisce un token di licenza firmato (JWT) insieme ai diritti. Il client memorizza questo JWT localmente nella cache. Se un successivo tentativo di validazione fallisce (errore di rete, timeout), il client utilizza il JWT memorizzato.

Il JWT di licenza contiene:

{
  "sub": "key_abc123",
  "iss": "https://api.altovar.net",
  "iat": 1710000000,
  "exp": 1710086400,
  "entitlements": {
    "features": ["advanced-analytics", "api-access"],
    "maxSeats": 10,
    "maxDevices": 5
  },
  "policy": "pol_enterprise",
  "licensee": {
    "type": "organization",
    "id": "org_xyz"
  }
}

Il JWT è firmato con la chiave privata del tenant (RS256). L’applicazione verifica la firma utilizzando la chiave pubblica dall’endpoint JWKS — nessuna chiamata di rete ad Auris necessaria per la validazione dalla cache.

Punti di forza: Funziona offline per la durata del claim exp del JWT. I controlli online mantengono i diritti aggiornati. Degradazione graduale.

Punti deboli: Durante i periodi offline, le revoche e le modifiche ai diritti non si riflettono fino alla scadenza del JWT e al successo di un nuovo controllo online.

Ideale per: Applicazioni desktop, app mobile e ambienti con connettività intermittente.

Validazione Offline

Validazione solo tramite JWT senza alcuna dipendenza dalla rete:

Client → Verifica firma JWT localmente → Controlla claim exp → Leggi diritti

Il JWT di licenza viene emesso una sola volta (durante l’attivazione) e memorizzato sul client. Ogni controllo di validazione è un’operazione crittografica locale — verifica della firma, controllo della scadenza, lettura dei diritti.

Punti di forza: Nessuna dipendenza dalla rete. Validazione in meno di un millisecondo. Funziona in ambienti air-gapped.

Punti deboli: Le modifiche ai diritti richiedono la riemissione e la reimportazione del JWT. Le revoche si basano sul meccanismo separato della lista di revoca (vedi Revoca).

Ideale per: Software on-premise, sistemi embedded, ambienti air-gapped e qualsiasi scenario in cui il client non può o non dovrebbe contattare un’API esterna.

Licenze Floating

Le licenze tradizionali basate su postazioni assegnano le postazioni in modo permanente — se si hanno 10 postazioni, solo 10 utenti nominati possono utilizzare il software. Le licenze floating adottano un approccio diverso: le postazioni vengono concesse temporaneamente in prestito e restituite quando non sono più in uso.

Questo è ideale per le organizzazioni in cui molti dipendenti necessitano di accesso occasionale ma pochi utilizzano il software contemporaneamente. Un’azienda con 50 dipendenti potrebbe aver bisogno di sole 10 postazioni floating se non più di 10 persone utilizzano il software nello stesso momento.

Come funzionano le licenze floating

Il ciclo di vita delle licenze floating prevede tre operazioni:

Checkout

Quando un utente avvia l’applicazione, il client richiede un lease di postazione ad Auris:

POST /api/licensing/checkout
{
  "key": "key_abc123",
  "userId": "user_alice",
  "leaseDuration": 30  // minutes
}

Auris verifica se una postazione è disponibile (lease attivi correnti < postazioni massime). Se una postazione è disponibile, crea un record di lease con un tempo di scadenza e restituisce un token di lease. Se tutte le postazioni sono occupate, il checkout fallisce con un errore SEATS_EXHAUSTED.

Heartbeat

Mentre l’utente utilizza attivamente il software, il client estende periodicamente il lease:

POST /api/licensing/heartbeat
{
  "leaseId": "lease_xyz",
  "extend": 30  // minutes
}

L’heartbeat reimposta il timer di scadenza del lease. Se il client smette di inviare heartbeat (crash dell’applicazione, perdita di rete, utente assente), il lease scadrà naturalmente.

Checkin

Quando l’utente chiude l’applicazione, il client rilascia esplicitamente la postazione:

POST /api/licensing/checkin
{
  "leaseId": "lease_xyz"
}

Il lease viene eliminato immediatamente, liberando la postazione per un altro utente. Se il client non effettua il checkin (crash, chiusura forzata), il lease scade automaticamente dopo il termine della durata del lease.

Scadenza e recupero del lease

Il meccanismo di scadenza automatica è fondamentale per le licenze floating. Senza di esso, un client in crash consumerebbe permanentemente una postazione. Auris esegue una pulizia periodica che rimuove i lease scaduti, garantendo che le postazioni siano sempre recuperabili.

La durata del lease è un equilibrio tra reattività e resilienza:

• Lease brevi (5-10 minuti): Le postazioni vengono recuperate rapidamente dopo un crash, ma il traffico di heartbeat è maggiore.
• Lease lunghi (30-60 minuti): Meno traffico di heartbeat, ma un client in crash occupa una postazione più a lungo.

Il valore predefinito consigliato è 15-30 minuti, con heartbeat inviati a metà dell’intervallo del lease.

Attivazione Offline

Alcuni ambienti non hanno alcun accesso alla rete — sistemi di produzione industriale, reti governative classificate, dispositivi medici, sistemi di controllo industriale. Per questi scenari, Auris supporta un flusso di attivazione completamente offline che non richiede mai al client di comunicare direttamente con l’API di Auris.

Il flusso di attivazione offline

Il processo coinvolge un intermediario umano che trasporta i dati tra la macchina air-gapped e una macchina con accesso all’API/console:

Passo 1: Il client genera un payload di richiesta

L’applicazione client raccoglie la chiave di licenza e un fingerprint del dispositivo, li impacchetta in un payload strutturato e lo codifica come stringa base64:

{
  "key": "key_abc123",
  "fingerprint": "fp_sha256_a1b2c3d4e5f6...",
  "requestedAt": "2025-06-15T10:30:00Z",
  "clientVersion": "2.4.1"
}

L’utente copia questa stringa base64 (visualizzata come testo o codice QR) e la porta su una macchina connessa alla rete.

Passo 2: L’amministratore invia la richiesta

L’amministratore incolla il payload di richiesta nella Console Auris (sotto Licensing > Offline Activations) o lo invia tramite l’API:

POST /api/licensing/activate/offline
{
  "requestPayload": "eyJrZXkiOiAia2V5X2FiYz..."
}

Auris valida la chiave, registra il fingerprint del dispositivo e genera un token di risposta firmato — un JWT contenente i diritti completi, legato allo specifico fingerprint del dispositivo.

Passo 3: Il client importa il token di risposta

L’amministratore copia il token di risposta sulla macchina air-gapped. L’applicazione client lo importa, verifica la firma con una chiave pubblica inclusa nel pacchetto o precedentemente ottenuta, e attiva la licenza.

Da questo punto in avanti, il client valida la licenza interamente offline verificando la firma del JWT e controllandone i claim.

Fingerprinting del dispositivo

Le licenze legate al dispositivo richiedono un modo per identificare le macchine in modo affidabile. Auris utilizza un fingerprint composito costruito da molteplici attributi hardware e del sistema operativo, trasformati in un identificativo stabile tramite hash.

Il fingerprint viene calcolato a partire da una combinazione di:

• Modello e numero di core della CPU
• Memoria di sistema totale
• Tipo e versione del sistema operativo
• Numeri seriali dei dischi
• Indirizzi MAC delle interfacce di rete (filtrati per escludere gli adattatori virtuali)
• Machine ID o UUID hardware (specifico per piattaforma)

Nessun singolo attributo viene utilizzato isolatamente, perché qualsiasi attributo può cambiare (un upgrade della RAM, una nuova scheda di rete). Il fingerprint utilizza invece un algoritmo di corrispondenza basato su soglia: se un numero sufficiente di attributi corrisponde ancora, il fingerprint è considerato come la stessa macchina. Questo tollera modifiche hardware minori pur rilevando quando una licenza è stata spostata su una macchina fondamentalmente diversa.

La soglia è configurabile per policy:

Quando viene rilevata una discrepanza di fingerprint oltre la tolleranza configurata, la validazione fallisce con un errore DEVICE_MISMATCH. L’utente finale deve disattivare il vecchio dispositivo (se accessibile) o contattare l’amministratore per reimpostare il vincolo del dispositivo.

Revoca

Revocare una chiave di licenza significa impedire permanentemente o temporaneamente il superamento della validazione. La rapidità con cui la revoca ha effetto dipende dalla modalità di validazione.

Revoca Online

Quando una chiave viene revocata e il client utilizza la validazione online, la revoca è immediata. La successiva chiamata POST /api/licensing/validate restituisce:

{
  "ok": true,
  "data": {
    "valid": false,
    "code": "KEY_REVOKED",
    "message": "This license key has been revoked."
  }
}

Non è necessario alcun meccanismo aggiuntivo — il server è la fonte di verità.

Revoca Offline

Quando il client utilizza la validazione offline o ibrida, il JWT della chiave revocata rimane crittograficamente valido fino alla sua scadenza. Per risolvere questo problema, Auris pubblica una lista di revoca — un JWT firmato contenente un array di identificativi delle chiavi revocate e i relativi timestamp di revoca.

{
  "iss": "https://api.altovar.net",
  "iat": 1710000000,
  "exp": 1710086400,
  "revoked": [
    { "key": "key_abc123", "revokedAt": "2025-06-15T14:00:00Z" },
    { "key": "key_def456", "revokedAt": "2025-06-14T09:30:00Z" }
  ]
}

I client che supportano la validazione offline dovrebbero recuperare periodicamente la lista di revoca dall’endpoint well-known (GET /api/licensing/.well-known/revocation-list) e memorizzarla localmente nella cache. Durante la validazione offline, il client verifica il JWT di licenza e la lista di revoca memorizzata nella cache.

Periodo di grazia e TTL

La revoca negli scenari offline è intrinsecamente ritardata. Due opzioni di configurazione controllano il compromesso:

Il periodo di grazia esiste per evitare interruzioni brusche in ambienti dove la connettività è rara. Un client air-gapped che recupera la lista di revoca settimanalmente rispetterà comunque le revoche entro la finestra di grazia. Dopo il periodo di grazia, la chiave viene bloccata rigidamente indipendentemente dallo stato della cache.

Portale Clienti

Auris Licensing include un portale rivolto al cliente dove gli utenti finali (licenziatari) possono visualizzare e gestire le proprie licenze senza contattare il fornitore del software.

Come funziona

Il portale clienti è accessibile tramite lo stesso flusso di login ospitato da Auris utilizzato per l’autenticazione. Quando un utente accede, vede solo le licenze associate al proprio account — direttamente (chiavi legate all’utente) o tramite la propria appartenenza organizzativa (chiavi legate all’organizzazione).

Il portale fornisce:

• Panoramica licenze: Tutte le chiavi attive, scadute e sospese con i relativi diritti
• Gestione dispositivi: Visualizzazione dei dispositivi attivati, disattivazione di un dispositivo per liberare uno slot
• Token offline: Download dei JWT di licenza firmati per l’uso offline
• Storico utilizzo: Utilizzo delle postazioni nel tempo (per licenze floating)
• Stato dei rinnovi: Date di scadenza e link per il rinnovo (se l’integrazione con i pagamenti è configurata)

Separazione dalla gestione amministrativa

Il portale clienti è distinto dalla Console Auris. Gli amministratori nella Console hanno il pieno controllo su tutte le licenze, policy e chiavi di tutti i clienti. Il portale clienti mostra solo ciò che appartiene all’utente autenticato.

Questa separazione significa:

• Gli utenti finali non possono vedere le licenze di altri clienti
• Gli utenti finali non possono modificare le impostazioni delle policy o creare nuove chiavi
• Gli utenti finali possono eseguire azioni self-service (disattivare un dispositivo, scaricare un token offline) senza intervento dell’amministratore
• Gli amministratori possono disabilitare specifiche azioni self-service per policy, se necessario

Automazione

La gestione manuale delle licenze non scala. Quando un cliente paga per il software, si desidera che la chiave di licenza venga emessa automaticamente. Quando un abbonamento decade, si desidera che la chiave venga sospesa. Auris Licensing si integra con i provider di pagamento e il sistema di eventi di Auris per automatizzare l’intero ciclo di vita.

Integrazione webhook per i pagamenti

Auris supporta l’integrazione diretta con Stripe e PayPal per la gestione delle licenze guidata dai pagamenti:

Stripe:

• checkout.session.completed → Crea una nuova chiave in base alla policy appropriata
• invoice.paid → Estende la scadenza della chiave (rinnovo abbonamento)
• invoice.payment_failed → Sospende la chiave (periodo di grazia configurabile)
• customer.subscription.deleted → Revoca o fa scadere la chiave

PayPal:

• PAYMENT.SALE.COMPLETED → Crea una nuova chiave
• BILLING.SUBSCRIPTION.RENEWED → Estende la scadenza
• BILLING.SUBSCRIPTION.CANCELLED → Revoca o fa scadere la chiave
• BILLING.SUBSCRIPTION.SUSPENDED → Sospende la chiave

Mappatura Evento-Azione

Oltre ai webhook di pagamento, il sistema di eventi di Auris consente di definire regole di automazione personalizzate. Qualsiasi evento di licenza può attivare un’azione:

Queste regole vengono configurate nella Console Auris sotto Licensing > Automation Rules o tramite l’API. Si integrano con lo stesso Actions Engine utilizzato per i flussi di autenticazione, così da poter utilizzare azioni JavaScript personalizzate per logica complessa.

Come si integra il tutto

Le licenze in Auris non sono una funzionalità isolata — sono integrate nella più ampia piattaforma di gestione delle identità e degli accessi:

• Utenti e organizzazioni di Auris IAM sono i licenziatari. Non è necessario un database utenti separato.
• L’autenticazione tramite Auris Hosted Login controlla l’accesso al portale clienti.
• I permessi RBAC controllano chi può gestire le licenze nella Console (manage:licenses, view:licenses).
• FGA può essere utilizzato insieme alle licenze per l’accesso granulare alle risorse all’interno di un’applicazione licenziata.
• I webhook notificano i tuoi sistemi degli eventi di licenza in tempo reale.
• I log di audit registrano ogni operazione di licenza (chiave creata, validata, revocata, dispositivo attivato).

Questa integrazione significa che gli utenti vengono definiti una sola volta, autenticati una sola volta, e sia il controllo degli accessi che le licenze vengono gestiti da un’unica piattaforma.

Concetti correlati

• Sessioni & Rotazione Token — Come funzionano le sessioni e i JWT in Auris
• I Token Spiegati — Struttura, firma e verifica dei JWT
• Actions & Esecuzione Sandbox — Logica di automazione personalizzata per gli eventi di licenza
• Multi-Tenancy — Come funzionano le licenze tra i tenant
• OAuth 2.0 & OIDC — Il framework di autenticazione alla base del portale clienti