How to Migrate an Existing Data Publisher to an Event Handler

Up to WSO2 Identity Server version 5.7.0, data publishers were the implementations of AbstractAuthenticationDataPublisher invoked iteratively by the AuthnDataPublisherProxy when a session is changed, such that these data publishers send events to their corresponding destinations. But from WSO2 IS 5.8.0 onwards, these data publishers are now migrated to act as event handlers that subscribe to authentication events.

So according to this design approach,

• When a session is changed, the identity-framework publishes an event to the AuthnDataPublisherProxy.
• AuthnDataPublisherProxy uses the IdentityEventService in identity-framework to invoke corresponding handlers to handle the event.
• These event handlers extend the AbstractEventHandler and override its handleEvent method.

So now let’s look into how to migrate a data publisher to an event handler. For this, I will be using DASSessionDataPublisherImpl which is now deprecated to use AnalyticsSessionDataPublishHandler. From here onwards, I will refer <IS_HOME> as the directory where the WSO2 Identity Server is installed.

1. First of all, the listener configuration corresponding to the data publisher added in <IS_HOME>/repository/conf/identity/identity.xml file should be removed. For DASSessionDataPublisherImpl, the following config is removed. You can do this in code level by editing the identity.xml in here.

2. In order to support backward compatibility, isEnabled method should be overridden in the event handler class that extends the AbstractEventHandler, such that if the listener property is not defined in the identity.xml it will return false.

3. So as to enable the new event handler, a property should be added to the identity-event.properties file stored in the <PRODUCT_HOME>/repository/conf/identity/ directory. This can be done in code level by editing this file.

For AnalyticsSessionDataPublishHandler, it is defined as follows.

4. In order to check whether the handler is enabled or not, the following method should be added to the event handler.

5. One of the main reasons to deprecate the implementation of data publishers is that these data publishers override all the methods of AbstractAuthenticationDataPublisher. Due to this redundancy, it was decided to change this implementation such that these publishers should get subscribed only to their relevant event.

According to the implementation of DASSessionDataPublisherImpl as shown above, it publishes data only for the following three events.

• Session Create
• Session Terminate
• Session Update

Therefore the event handler written for this data publisher should handle only the above-mentioned events. So AnalyticsSessionDataPublishHandler overrides the handleEvent method as follows.

Here, in order to invoke the corresponding publishing method, it is verified first that the handler is enabled or not. The buildSessionData method of SessionDataPublisherUtil is introduced to create a session data object to populate the payload of the relevant event.

6. Same as the implementation of the DASSessionDataPublisherImpl data publisher, next, the payload of the event of AnalyticsSessionDataPublishHandler should be populated. And then it is published to analytics. So the final implementation of the AnalyticsSessionDataPublishHandler class will look as follows.

7. Finally, the service should be registered for OSGi runtime as follows.

Hope now you are clear on how to migrate an existing data publisher in WSO2 Identity Server to an event handler that subscribes to authentication events. You can even write new such event handlers that can be plugged into WSO2 IS following this guide.

Please do comment below for any clarifications or questions.😊

Thanks!