Riporto la traccia di ciò che ho presentato al Liferay Bootcamp 2013 sul servizio di audit presente in Liferay EE.

L'esigenza

Molte organizzazioni hanno la necessità di registrare le azioni compiute dagli utenti del sistema. Alcuni domini applicativi e alcune nazioni richiedono di memorizzare questi dati per poter effettuare analisi successive. La necessità di registrare le azioni degli utenti è ancor più sentita quando nel sistema ci sono vari profili utente con differenti livelli di amministrazione. La gestione di questa tracciabilità avviene mediante degli appositi messaggi, chiamati "Audit trails".

Nella User Guide presente nel sito pubblico di Liferay è presente un simpatico esempio che illustra un caso in cui sono state disassociate per errore le membership degli utenti ai relativi gruppi, la gestione degli audit trails ha permesso di risalire all'utente che ha causato il problema.
 

Architettura

L'architettura si basa su un servizio di Audit, chiamato "Audit Service", che fornisce un meccanismo flessibile per l'inserimento di messaggi di audit da parte di Liferay e dei suoi plugin. Questo servizio è lui stesso un plugin che si occupa di processare e loggare i messaggi di audit ricevuti tramite il message bus. I messaggi di audit inviati verso la destinazione del message bus del servizio di audit possono essere prodotti da qualunque plugin che abbia la necessità di gestire gli audit trails. Questo approccio permette di disaccoppiare la generazione dei messaggi dalla fase di gestione degli stessi.

Il servizio di audit è incluso nel plugin "Audit Plugin", disponibile solo per la versione EE. Questo plugin sfrutta alcune classi già presenti nel kernel di Liferay integrando la gestione dei messaggi di audit. Questo plugin include anche un portlet per la visualizzazione dei messaggi di audit memorizzati sul database. Con il plugin di audit viene caricato anche un altro plugin chiamato "Audit Hook", il quale innesta tramite hook la generazione di alcuni messaggi di audit, che possono essere presi come punto di partenza per l'implementazione dei propri messaggi di audit:

• Eventi
  • LoginFailure
  • ImpersonationAction
  • LoginPostAction
  • LogoutPostAction
• Listener
  • AddressListener
  • ContactListener
  • RoleListener
  • UserListener
  • UserGroupListener
  • UserGroupRoleListener

La figura di seguito (presa dalla guida ufficiale Liferay) illustra le componenti coinvolte con i due plugin "Audit Plugin" e "Audit Hook".

Liferay mette a disposizione una servlet che si chiama AuditFilter, che permette di gestire i dettagli della richiesta da includere nei messaggi di audit. Questa servlet si trova nativamente in Liferay, quindi è presente anche se non è stato deployato il plugin di audit. Per questo motivo questa servlet è disabilitata di default ma può essere facilmente attivata mediante una proprietà presente nel portal.properties: com.liferay.portal.servlet.filters.audit.AuditFilter=true.

Le informazioni della richiesta sono gestite mediante una variabile locale del thread di esecuzione di tipo AuditRequestThreadLocal. È importante notare che la variabile locale che contiene le informazioni della richiesta permette anche di capire se si sta impersonando un utente, in modo da tenere traccia anche dell'utente originale e non solo di quello impersonato.

Per creare un messaggio di audit si utilizza la classe AuditMessage che fa parte del kernel di Liferay e che viene gestita dal "Audit Plugin". La classe AuditMessage permette di indicare i dettagli del messaggio di audit che si vuole gestire, inoltre si occupa di reperire automaticamente le informazioni sul client che sono disponibili solo se si abilita la servlet AuditFilter.

Per garantire una più facile gestione e estensione la classe AuditMessage permette di indicare delle informazioni aggiuntive rispetto alla struttura di base di un messaggio di audit mediante il parametro "additionalInfo". Questo parametro permette di indicare queste informazioni aggiuntive utilizzando il formato JSON.

Di seguito il formato di un messaggio di audit.

• message (String): Il messaggio da catturare
• eventType (String): Il tipo di evento da catturare e gestire
• companyId (long): Il companyId dell'istanza di portale
• userId (long): Lo User ID dell'utente che compie l'azione
• userName (String): Lo Username dell'utente che compie l'azione
• className (String): Il class name id del modello oggetto dell'azione
• classPK (String): La chiave primaria dell'oggetto dell'azione
• type (String): Tipo di azione
• sessionID (String): ID della sesssione HTTP
• clientIP (String): IP remoto del cliente che esegue l'azione
• serverIP (String): IP del server da cui ha origine l'azione (utile per gli ambienti in cluster)
• timestamp (Datetime): Il timestamp dell'evento
• additionalInfo (String): Informazioni aggiuntive che possono essere incluse nel messaggio, si utilizza il formato JSON

Il plugin di audit registra una nuova destinazione sul message bus: liferay/audit, su questa destinazione c'è in ascolto il listener AuditMessageListener. Questa configurazione avviene mediante il file messaging-spring.xml incluso nel plugin di audit. I messaggi sono indirizzati presso la destinazione del message bus mediante una utility di routing: com.liferay.portal.kernel.audit.AuditRouterUtil.route(). Questa classe fa parte del kernel di Liferay ed indirizza i messaggi verso la destinazione di audit del message bus che viene registrata dal "AuditPlugin".

Il listener indirizza i messaggi verso delle cassi che sono in grado di processare i messaggi di audit, queste classi devono implementare l'interfaccia AuditMessageProcessor. La configurazione dei processori da cui devono essere processati i messaggi di audit si effettua nel file audit-spring.xml. In questo file possibile è possibile aggiungere implementazioni di processori custom. Il plugin di audit fornisce due implementazioni predefinite: il DatabaseProcessor per inserire i messaggi di audit in tabelle del database e il Log4JProcessor per memorizzare i messaggi in appositi file di log. È possibile configurare dei processori globali e dei processori che devono essere invocati solo per determinati tipi di eventi, in questo modo è possibile differenziare il luogo dove memorizzare le azioni in base alla loro tipologia. Ad esempio potremmo decidere di memorizzare i messaggi di login e logout su file system, mentre i messaggi prodotti dal nostro plugin nel database. La configurazione predefinita del plugin di audit memorizza i messaggi di audit nel database, per memorizzarli anche nel file di log è necessario modificare opportunamente il livello di log della classe "LogAuditRouterProcessor".

La scelta del processore da utilizzare è molto importante perché il numero di messaggi di audit potrebbe crescere molto rapidamente, quindi potrebbe impattare sulle prestazioni.

Ricapitolando, per poter gestire i messaggi di audit dall'interno dei nostri plugin è necessario:

1. Creare e popolare un messaggio di audit, tramite un'istanza di com.liferay.portal.kernel.audit.AuditMessage
2. Instradare il messaggio verso la destinazione del message bus mediante l'utility com.liferay.portal.kernel.audit.AuditRouterUtil.route()

È conveniente creare delle classi di supporto per la creazione dei messaggi di audit e per la costruzione delle informazioni aggiuntive da associare al messaggio di audit mediante il paramentro "additionalInfo". È importante notare che è possibile creare dei processori custom che siano in grado di gestire opportunamente il campo "additionalInfo", ad esempio strutturando in modo opportuno le informazioni in esso contenute.

La gestione dei messaggi di audit viene generalmente fatta in risposta a determinati eventi di creazione/modifica/cancellazione/cambio di stato, quindi può essere utile utilizzare un listener in ascolto su determinati eventi, ad esempio un listner di modello della entità per cui tracciare i messaggi di audit.

I messaggi di audit registrati nel sistema possono essere consultati mediante un portlet che viene fornito con l'audit plugin, il suo nome è "Audit Reports". Questo portlet è generico e permette di effettuare le ricerche sui principali campi di cui si compone un messaggio di audit. Questo portlet può essere utilizzato così com'è oppure può rappresentare un buon punto di partenza per la realizzazione di un proprio portlet di ricerca dei messaggi di audit.

Ho proseguito poi il talk parlando dell'integrazione con Jasper Report, disponibile anche in questo caso solo per la versione EE di Liferay, mostrando un documento contenente tutti i messaggi di audit tracciati per l'entità custom gestita nei vari talk del bootcamp.

In caso di necessità di approfondimenti sulla piattaforma Liferay o più nello specifico sul servizio di audit, potete contattare ViVieb mediante l'apposito modulo contatti presente sul sito o potete contattarmi direttamente inviandomi un email all'indirizzo graziano@vivieb.it

A breve renderemo disponibili anche il plugin che abbiamo realizzato durante il bootcamp.

Ciao!