Come abilitare un JAX-WS Handler per fare audit dei messaggi SOAP via Liferay Audit Framework

Con il precedente articolo How to implement a SOAP client using JAX-WS Liferay infrastructure abbiamo avuto modo di vedere come realizzare un client SOAP utilizzando l’infrastruttura JAX-WS che Liferay mette a disposizione a noi sviluppatori.

In questo articolo andremo un pochino oltre, vedendo come sfruttare i JAX-WS Handler ed il Liferay Audit Framework con l’obiettivo di fare audit dei messaggi SOAP (di request e response) dei nostri Web Services SOAP custom. Per finire vi lascerò un bel bonus.

Se vorresti approfondire la tematica su come sviluppare servizi SOAP e REST su Liferay in standard JAX-WS e JAX-RS, ti consiglio di leggere il documento How to develop SOAP and REST services in JAX-WS and JAX-RS standard on Liferay presentato al Liferay Symposium Italia del 2016.

Per quanto riguarda gli approfondimenti su Liferay Audit ti consiglio di scaricare il materiale del Liferay Boot Camp 2019 tenuto il 16 maggio a Roma e organizzato da SMC. Oltre al tema di #SecurityAudit, ne sono stati trattati tanti altri interessanti.

Tutto il codice mostrato in questo articolo è disponibile sul repository GitHub liferay-72-soap-client-examples e testato su Liferay 7.2 GA1.

 

1. Il caso d’uso

Mettiamo il caso di aver sviluppato qualche tempo addietro un servizio SOAP e che adesso è sopraggiunta la necessità di fare audit trail su questo web service, ovvero, ci chiedono di voler tracciare i messaggi SOAP (di richiesta e risposta). Come realizzare questa necessità?

Tutto quello che serve per raggiungere l’obiettivo è già disponibile all’interno della borsa attrezzi di Liferay. Gli attrezzi che andremo ad usare sono:

  • Il Liferay Audit Framework
  • Il Liferay SOAP Extender
  • JAX-WS Handler API

 

2. Come implementare il JAX-WS Handler

Dall’analisi dei requisiti, dovremmo sviluppare un JAX-WS Handler di tipo Protocol Handler perchè il livello trattato e quello di protocollo, in questo caso SOAP.

Siamo in un contesto OSGi, pertanto l’handler sarà realizzato come OSGi Component (Declarative Services Specification) e frutterà le API di Audit di Liferay con l’obiettivo di catturare e inviare i messaggi SOAP di in bound e di out bound  verso il sistema di audit.

Audit Log Handler è il nome del componente OSGi che implementa un JAX-WS Handler e in particolare un SOAPHandler.

Del codice mostrato, fare attenzione alle due proprietà del component che sono evidenziate, ovvero, service property. La prima proprietà specifica l’interfaccia del servizio, in questo caso javax.xml.ws.handler.Handler, la seconda imposta una coppia chiave valore che sarà poi utilizzata (via OSGi Filter) dal Liferay Extender per attivare l’handler.

È consigliabile utilizzare per l’OSGi Filter una chiave che sia auto esplicativa e credo che audit.log.jax.ws.handler.filters=true lo sia.

 

La gestione del messaggio SOAP (compreso quello di fault) avviene attraverso il metodo privato _doHandleMessage(context) richiamato dai due metodi pubblici dell’interfaccia Handler:

 

Il codice a seguire mostra l’implementazione del metodo _doHandleMessage(SOAPMessageContext context) che in particolare:

  1. Scrive su un Byte Array Output Stream il messaggio SOAP;
  2. Prepara uno specifico messaggio di audit, sia per il messaggio SOAP in bound sia per quello di out bound utilizzando il metodo statico AuditEventUtil.getAuditMessage();
  3. Invia il messaggio di audit al sistema di Audit di Liferay utilizzando il metodo statico AuditEventUtil.sendAuditMessage().

 

 

Le informazioni di nostro interesse tracciate dal sistema di audit sono:

  1. Il tipo di evento che può essere SERVICE_SOAP_TRACE_INBOUND_EVENT o SERVICE_SOAP_TRACE_OUTBOUND_EVENT;
  2. Il correlationId il cui contenuto è l’UUID e il cui scopo è l’associazione tra richiesta e risposta del messaggio SOAP;
  3. Il messaggio SOAP.

L’implementazione di questo JAX-WS Handler è ultimata e il prossimo step sarà la configurazione la cui applicazione aggancerà l’handler al nostro servizio SOAP.

 

3. Configurazione del JAX-WS Handler per il servizio SOAP

Se facessimo il deploy dell’Audit Log Handler sulla nostra istanza Liferay e provassimo ad invocare il servizio SOAP (per esempio via SOAP UI), non otterremmo il risultato atteso. Per quale motivo?

La motivazione è scritta all’inizio del paragrafo precedente, ovvero, il Liferay Extender deve essere informato circa i JAX-WS Handler che devono essere attivati per lo specifico endpoint SOAP. Come si fa quest’operazione di configurazione?

La configurazione può essere eseguita attraverso il pannello di controllo: System Settings -> Web API -> SOAP Extenders, da qui accedere all’endpoint interessato e specificare il filtro (audit.log.jax.ws.handler.filters=true) all’interno della configurazione JAX-WS Handler Filters. Le figure a seguire renderanno meglio l’idea.

L’endpoint interessato, in questo caso /custom-user, corrisponde al servizio SOAP Custom User Service WS la cui implementazione è disponibile all’interno del modulo custom-users-ws.

Prima di procedere con la configurazione dovreste accertarvi che i seguenti moduli (che ricordo essere disponibili sul repository GitHub liferay-72-soap-client-examples) siano stati installati:

  1. Custom Users API
  2. Custom Users Service Implementation
  3. Custom Users Service JAX-WS API End Point

 

Figure 1 - SOAP Extender configuration

Figure 1 – SOAP Extender configuration

 

Figure 2 - Configuration of the JAX-WS Handler (Audit Log Handler)

Figure 2 – Configuration of the JAX-WS Handler (Audit Log Handler)

 

Una piccola nota. Il modulo custom-users-ws che contiene il servizio SOAP sottoposto ad audit, è stato impostato per la configurazione automatica che al momento però non sembra funzionare con Liferay 7.2 GA1 (vedi LPS-101642). Questo è il motivo per cui dobbiamo procedere con la configurazione manuale.

 

4. Test del JAX-WS Handler Audit Log Handler

Prima di poter eseguire un test dovreste accertarvi che i seguenti moduli (che ricordo essere disponibili sul repository GitHub liferay-72-soap-client-examples) siano stati installati:

  1. Custom Users API
  2. Custom Users Service Implementation
  3. Custom Users Service JAX-WS API End Point

Per verificare il corretto funzionamento dell’Audit Log Handler è sufficiente richiamare il servizio SOAP Custom User Service WS attraverso il tool SOAP UI o altro equivalente (come per esempio cURL o HTTPie).

Il documento WSDL del servizio è raggiungibile al seguente indirizzo http://[$FQDN|$HOSTNAME|$IP]:8080/o/custom-user/CustomUserServiceWSEndPoint?wsdl ma nella maggior parte dei casi l’indirizzo http://localhost:8080/o/custom-user/CustomUserServiceWSEndPoint?wsdl dovrebbe essere valido per tutte le installazioni locali di Liferay.

Le due figure a seguire mostrano due richieste SOAP (di cui una risposta è un fault) del servizio Custom User Service WS e in particolare per l’operazione getUsersByTags(). Quest’operazione restituisce gli utenti del sistema che hanno un determinato tag.

 

Figure 3 - Response of the SOAP Service Custom User

Figure 3 – Response of the SOAP Service Custom User

 

Figure 4 - Response (fault) of the SOAP Service Custom User

Figure 4 – Response (fault) of the SOAP Service Custom User

 

Molto bene 🙂 Il nostro componente JAX-WS Audit Log Handler avrà fatto il suo lavoro? Colleghiamoci al database di Liferay e facciamo una query come quella mostra subito sotto e che agisce sulla tabella AUDIT_AUDITEVENT.

 

 

Il risultato della query è mostrato nella figura a seguire da cui è possibile notare i due record per i due messaggi SOAP di richiesta e risposta che sono correlati attraverso il valore dell’attributo classPK che rappresenta il correlationId.

 

Figure 5 - View of the audit data collected by the JAX-WS Handler

Figure 5 – View of the audit data collected by the JAX-WS Handler

 

Il contenuto dell’attributo additionlInfo della tabella AUDIT_AUDITEVENT è un JSON il cui contenuto di esempio è mostrato a seguire.

 

 

Direi che potremmo benissimo affermare che il risultato prefissato è stato raggiunto con successo utilizzando gli strumenti che Liferay mette a nostra disposizione 🙂

 

5. Il bonus

All’inizio dell’articolo avevo scritto di un bonus. Di cosa si tratta? Ho voluto lasciarvi un ulteriore JAX-WS Handler con il quale potreste giocare. Troverete il codice all’interno del repository. Buona continuazione e divertimento. Fatemi sapere le vostre impressioni 😉

2 Condivisioni

Antonio Musarra

I began my journey into the world of computing from an Olivetti M24 PC (http://it.wikipedia.org/wiki/Olivetti_M24) bought by my father for his work. Day after day, quickly taking control until … Now doing business consulting for projects in the enterprise application development using web-oriented technologies such as J2EE, Web Services, ESB, TIBCO, PHP.

Potrebbero interessarti anche...

Cos'è il progetto CIE/CNS Apache Docker - Developers Italia

In questo video https://youtu.be/TcAzn1POhsM introdurrò il progetto CIE/CNS Apache Docker di Developers Italia (https://developers.italia.it/it/cie/#resourcecontent-3) nato circa due anni fa.

L'obiettivo di questo progetto è quello di fornire un template pronto all'uso che realizza un sistema di autenticazione tramite la Smart Card TS-CNS (o CNS) e la CIE (Carta d'Identità Elettronica) basato su Apache HTTP. Ognuno può poi modificare o specializzare questo progetto sulla base delle proprie esigenze Si tratta di un progetto docker per la creazione di un container che implementa un sistema di mutua autenticazione o autenticazione bilaterale SSL/TLS.

Questo meccanismo di autenticazione richiede anche il certificato digitale da parte del client, certificato che in questo caso risiede all'interno della TS-CNS o della CIE. La particolarità del sistema implementato (attraverso questo container) è quella di consentire l'autenticazione tramite:

  • La TS-CNS (Tessera Sanitaria - Carta Nazionale Servizi), rilasciata dalla regione di appartenenza;
  • La CIE (Carta d'Identità Elettronica), rilasciata dal comune di residenza.

Nella versione 2.0.0 il progetto è stato aggiornato per essere uniforme alle linee guida di Bootstrap Italia. A seguire alcune risorse che possono essere utili.

  • Cos’è il progetto CIE/CNS Apache Docker (http://bit.ly/3aJ5Gbl)
  • CIE Carta d'Identità Elettronica (https://developers.italia.it/it/cie/)
  • Carta Nazionale dei Servizi (https://www.agid.gov.it/it/piattaforme/carta-nazionale-servizi)
  • Raspberry Pi – Un esempio di applicazione della TS-CNS (https://bit.ly/3hkJ8Aj)
  • Pubblicare il servizio CIE/CNS Apache Docker su Azure Cloud (http://bit.ly/3aPoq8V)
  • Come accedere al portale VETINFO tramite TS-CNS e Mac OS (http://bit.ly/2VFMKq7)