How to enable a JAX-WS Handler to audit SOAP messages via the Liferay Audit Framework

by Antonio Musarra · 21 September 2019

With the previous article How to implement a SOAP client using JAX-WS Liferay infrastructure we were able to see how to build a SOAP client using the JAX-WS infrastructure that Liferay offers to developers.

In this article we will see how to exploit the JAX-WS Handlers and the Liferay Audit Framework with the aim of auditing SOAP messages (request and response) of our custom SOAP Web Services. Finally I will leave you a nice bonus.

If you would like to learn more about how to develop SOAP and REST services on Liferay in JAX-WS and JAX-RS standards, I suggest you read the document How to develop SOAP and REST services in JAX-WS and JAX-RS standard on Liferay that I have presented at the 2016 Liferay Symposium.

As for the in-depth information on Liferay Audit, I suggest you download the Liferay Boot Camp 2019 material held on May 16th in Rome and organized by SMC. In addition to the #SecurityAudit theme, many other interesting topics have been discussed.

All the code shown in this article is available on the GitHub repository liferay-72-soap-client-examples and tested on Liferay 7.2 GA1.

1. The use case

We have the case of having a SOAP service on which we need to do an audit trail, we need to track SOAP messages (request and response). How to realize this need?

Everything you need to reach the goal is already available inside Liferay’s tool kit. The tools we are going to use are:

The Liferay Audit Framework
The Liferay SOAP Extender
JAX-WS Handler API

2. How to implement the JAX-WS Handler

We should therefore develop a JAX-WS Handler of type Protocol Handler because the processed level is the protocol level, in this case SOAP.

We are in an OSGi context, therefore the handler will be implemented as OSGi Component (Declarative Services Specification) and will use the Liferay Audit API with the aim of capturing and sending SOAP messages of in bound and out bound to the system of audit.

Audit Log Handler is the name of the OSGi component that implements a JAX-WS Handler and in particular a SOAPHandler.

Of the code shown, pay attention to the two properties of the component that are highlighted, service and property. The first property specifies the service interface, in this case javax.xml.ws.handler.Handler, the second sets a key value pair that will then be used (via OSGi Filter) by the Liferay Extender to activate the handler.

It is advisable to use a key for OSGi Filter that is self explanatory and I believe that audit.log.jax.ws.handler.filters=true is.

@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) {
		...
	}

        ...
}

@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) {

...

}

...

}

The management of the SOAP message (including the fault one) is managed by the private _doHandleMessage (context) method called by the two public methods of the Handler interface:

The following code shows the implementation of the _doHandleMessage(SOAPMessageContext context) method which in particular:

Writes the SOAP message to a Byte Array Output Stream;
Prepare a specific audit message, both for the SOAP message in bound and for the out bound message using the static method AuditEventUtil.getAuditMessage();
Send the audit message to the Liferay Audit system using the static method AuditEventUtil.sendAuditMessage().

@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);
			}
		}
	}

	...
}

@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);

}

...

}

The information of interest to us drawn from the audit system is:

The type of event that can be SERVICE_SOAP_TRACE_INBOUND_EVENT or SERVICE_SOAP_TRACE_OUTBOUND_EVENT;
The correlationId whose content is the UUID and whose purpose is the association between request and response of the SOAP message;
The SOAP message.

The implementation of this JAX-WS Handler is complete and the next step will be the configuration whose application will hook the handler to our SOAP service.

3. Configuration of the JAX-WS Handler for the SOAP service

If we deployed the Audit Log Handler on our Liferay instance and tried to invoke the SOAP service (for example via SOAP UI), we would not get the expected result. For what reason?

The motivation is written at the beginning of the previous paragraph, the Liferay Extender must be informed about the JAX-WS Handlers that must be activated for the specific SOAP endpoint. How do you do this configuration operation?

The configuration can be performed through the control panel: System Settings -> Web API -> SOAP Extenders, from here access the affected endpoint and specify the filter (audit.log.jax.ws.handler.filters=true) to internal JAX-WS Handler Filters configuration. The following figures will make the idea better.

The affected endpoint, in this case /custom-user, corresponds to the SOAP Custom User Service WS service whose implementation is available within the custom-users-ws module.

Before proceeding with the configuration you should make sure that the following modules (which I remember are available on the GitHub liferay-72-soap-client-examples repository) have been installed:

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)

A small note. The custom-users-ws module containing the SOAP service subjected to the audit was set up for automatic configuration but at the moment does not seem to work with Liferay 7.2 GA1 (see LPS-101642). This is why we must proceed with manual configuration.

4. How to test the JAX-WS Handler Audit Log Handler

Before proceeding with the configuration you should make sure that the following modules (which I remember are available on the GitHub liferay-72-soap-client-examples repository) have been installed:

Custom Users API
Custom Users Service Implementation
Custom Users Service JAX-WS API End Point

To verify the correct operation of the Audit Log Handler it is sufficient to call the SOAP Custom User Service WS service through the SOAP UI tool or other equivalent (such as cURL or HTTPie).

The WSDL document of the service can be reached at the following address http://[$FQDN|$HOSTNAME|$IP]:8080/o/custom-user/CustomUserServiceWSEndPoint?wsdl but in most cases the address http://localhost:8080/o/custom-user/CustomUserServiceWSEndPoint?wsdl should be valid for all local Liferay installations.

The following two figures show two SOAP requests (of which one is a fault) of the Custom User Service WS service and in particular for the getUsersByTags() operation. This operation returns system users who have a specific tag.

Figure 3 – Response of the SOAP Service Custom User

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

Very good 🙂 Has our JAX-WS Audit Log Handler component done its job? Let’s connect to the Liferay database and make a query like the one shown below and that acts on the AUDIT_AUDITEVENT table.

select *
from audit_auditevent
where eventtype = 'SERVICE_SOAP_TRACE_EVENT'
order by createdate asc, classpk

select *

from audit_auditevent

where eventtype = 'SERVICE_SOAP_TRACE_EVENT'

order by createdate asc, classpk

The result of the query is shown in the following figure from which it is possible to note the two records for the two SOAP request and response messages that are correlated through the value of the classPK attribute that represents the correlationId.

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

The content of the additionlInfo attribute of the AUDIT_AUDITEVENT table is a JSON whose example content is shown below.

{
	"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"
}

{

"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 \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"

}

I would say that we could well say that the expected result was successfully achieved using the tools that Liferay offers 🙂

5. The bonus

At the beginning of the article I had written a bonus. What is it? I wanted to leave you an additional JAX-WS Handler that you could play with. You will find the code inside the repository. Good continuation and fun. Let me know your impressions 😉

Share2

2 Shares

Tags: Java Liferay SOAP API Web Services Web Services Framework

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.