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 e 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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
@Component( immediate = true, property = "audit.log.jax.ws.handler.filters=true", service = Handler.class ) public class AuditLogHandler implements SOAPHandler<SOAPMessageContext> { @Override public void close(MessageContext context) { } @Override public Set<QName> getHeaders() { return new HashSet<>(); } @Override public boolean handleFault(SOAPMessageContext context) { _doHandleMessage(context); return true; } @Override public boolean handleMessage(SOAPMessageContext context) { _doHandleMessage(context); return true; } private void _doHandleMessage(SOAPMessageContext context) { ... } ... } |
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:
- Scrive su un Byte Array Output Stream il messaggio SOAP;
- 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();
- Invia il messaggio di audit al sistema di Audit di Liferay utilizzando il metodo statico AuditEventUtil.sendAuditMessage().
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 |
@Component( immediate = true, property = "audit.log.jax.ws.handler.filters=true", service = Handler.class ) public class AuditLogHandler implements SOAPHandler<SOAPMessageContext> { ... private void _doHandleMessage(SOAPMessageContext context) { Boolean isOutBound = (Boolean)context.get( MessageContext.MESSAGE_OUTBOUND_PROPERTY); SOAPMessage soapMessage = context.getMessage(); String newCorrelationId = PortalUUIDUtil.generate(); String currentCorrelationId = GetterUtil.getString( context.get(_CORRELATION_ID)); if (Validator.isNull(currentCorrelationId)) { currentCorrelationId = newCorrelationId; context.put(_CORRELATION_ID, newCorrelationId); context.setScope(_CORRELATION_ID, MessageContext.Scope.APPLICATION); } try (ByteArrayOutputStream baos = new ByteArrayOutputStream()) { AuditMessage auditMessage; Map<String, Serializable> additionalInfo = new HashMap<>(); soapMessage.writeTo(baos); if (isOutBound) { additionalInfo.put( _OUT_BOUND_MESSAGE, new String(baos.toByteArray())); auditMessage = AuditEventUtil.getAuditMessage( additionalInfo, AuditLogHandler.class.getName(), currentCorrelationId, AuditEventKeys.SERVICE_SOAP_TRACE_OUTBOUND_EVENT. getAuditEventTypeCodeDescription(), AuditEventKeys.SERVICE_SOAP_TRACE_OUTBOUND_EVENT. getAuditEventTypeCode(), AuditEventKeys.SERVICE_SOAP_TRACE_OUTBOUND_EVENT. getAuditEventTypeId(), AuditEventKeys.SERVICE_SOAP_TRACE_OUTBOUND_EVENT. getAuditEventTypeCodeDescription()); } else { additionalInfo.put( _IN_BOUND_MESSAGE, new String(baos.toByteArray())); auditMessage = AuditEventUtil.getAuditMessage( additionalInfo, AuditLogHandler.class.getName(), currentCorrelationId, AuditEventKeys.SERVICE_SOAP_TRACE_INBOUND_EVENT. getAuditEventTypeCodeDescription(), AuditEventKeys.SERVICE_SOAP_TRACE_INBOUND_EVENT. getAuditEventTypeCode(), AuditEventKeys.SERVICE_SOAP_TRACE_INBOUND_EVENT. getAuditEventTypeId(), AuditEventKeys.SERVICE_SOAP_TRACE_INBOUND_EVENT. getAuditEventTypeCodeDescription()); } AuditEventUtil.sendAuditMessage(auditMessage); } catch (IOException | SOAPException e) { if (_log.isErrorEnabled()) { _log.error(e.getMessage(), e); } } } ... } |
Le informazioni di nostro interesse tracciate dal sistema di audit sono:
- Il tipo di evento che può essere SERVICE_SOAP_TRACE_INBOUND_EVENT o SERVICE_SOAP_TRACE_OUTBOUND_EVENT;
- Il correlationId il cui contenuto è l’UUID e il cui scopo è l’associazione tra richiesta e risposta del messaggio SOAP;
- 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:
- Custom Users API
- Custom Users Service Implementation
- Custom Users Service JAX-WS API End Point
Figure 1 – SOAP Extender configuration
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:
- Custom Users API
- Custom Users Service Implementation
- 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 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.
|
1 2 3 4 |
select * from audit_auditevent where eventtype = 'SERVICE_SOAP_TRACE_EVENT' order by createdate asc, classpk |
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
Il contenuto dell’attributo additionlInfo della tabella AUDIT_AUDITEVENT è un JSON il cui contenuto di esempio è mostrato a seguire.
|
1 2 3 4 5 6 |
{ "inBoundMessage": "<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:soap=\"soap\" xmlns:ws=\"http://ws.service.customusers.webservice.liferay.labs.dontesta.it/\">\n <soapenv:Header>\n <mac:MacAddress xmlns:mac=\"http://ws.service.customusers.webservice.liferay.labs.dontesta.it/macaddress/value/\" soapenv:actor=\"http://schemas.xmlsoap.org/soap/actor/next\">88:e9:fe:69:c6:88<\/mac:MacAddress>\n <\/soapenv:Header>\n <soapenv:Body>\n <ws:getUsersByTag>\n <!--Optional:-->\n <arg0>smc<\/arg0>\n <\/ws:getUsersByTag>\n <\/soapenv:Body><\/soapenv:Envelope>", "auditEventCode": "SERVICE_SOAP_TRACE_INBOUND_EVENT_0000", "auditEventDescription": "Trace SOAP Inbound Message", "auditEventType": "SERVICE_SOAP_TRACE_EVENT" } |
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 😉
