Write a Custom Event Handler¶

The MWARE IAM eventing framework can be used to trigger events such as user operation events like PRE_SET_USER_CLAIMS,POST_ADD_USER. A full list of the sample events can be found below. The eventing framework also supports handlers which can be used to do operations upon a triggered event. For instance, an event handler can be used to validate the changed user password against previously used entries when a PRE_UPDATE_CREDENTIAL event is triggered.

What is an event handler?¶

An event handler is used to perform an operation based on the published events.

For instance, an event handler can be used to send an email after a user addition. The following sequence of operations are executed while adding a user.

1. Publish the PRE_ADD_USER event — The subscribed handlers will be executed for the pre-add user event.
2. Execute the AddUser operation — The user will be persisted to the user store (LDAP or JBDC user store).
3. Publish the POST_ADD_USER event — The subscribed handlers will be executed for the post-add user event.

Therefore, the email can be sent through an event handler that is subscribed to the POST_ADD_USER event.

The following list is a list of sample events.

• AUTHENTICATION_STEP_SUCCESS
• AUTHENTICATION_STEP_FAILURE
• AUTHENTICATION_SUCCESS
• AUTHENTICATION_FAILURE
• PRE_AUTHENTICATION
• POST_AUTHENTICATION
• PRE_SET_USER_CLAIMS
• POST_SET_USER_CLAIMS
• PRE_ADD_USER
• POST_ADD_USER

Write an event handler¶

To write a new event handler, you must extend the org.wso2.carbon.identity.event.handler.AbstractEventHandler.

1. Override the getName() method to set the name for the event handler and the getPriority() method can be used to set the priory of the event handler. The handlers will be executed based on the priority.

   public String getName() {
   return "customEventHandler";
   }
   
   @Override
   public int getPriority(MessageContext messageContext) {
       return 50;
   }

2. To execute the expected operation, override the handleEvent() method. The event.getEventProperties() method can be used to get the parameters related to the user operations. The handleEvent() method should be called from the relevant method, which is written to execute a certain operation and the handlers will be executed once the operation is triggered.

   @Override
   public void handleEvent(Event event) throws IdentityEventException {
   
   Map<String, Object> eventProperties = event.getEventProperties();
   String userName = (String) eventProperties.get(IdentityEventConstants.EventProperty.USER_NAME);
   UserStoreManager userStoreManager = (UserStoreManager) eventProperties.get(IdentityEventConstants.EventProperty.USER_STORE_MANAGER);
   
   String tenantDomain = (String) eventProperties.get(IdentityEventConstants.EventProperty.TENANT_DOMAIN);
   String domainName = userStoreManager.getRealmConfiguration().getUserStoreProperty(UserCoreConstants.RealmConfig.PROPERTY_DOMAIN_NAME);
   
   String[] roleList = (String[]) eventProperties.get(IdentityEventConstants.EventProperty.ROLE_LIST);

Register the event handler¶

Register the event handler in the service component as follows.

protected void activate(ComponentContext context) {
    try {
        BundleContext bundleContext = context.getBundleContext();
        bundleContext.registerService(AbstractEventHandler.
class.getName(),new SampleEventHandler(), null);
    } catch (Exception e) {
       ...
    }

Configure the event handler¶

Add the event handler configuration to the <IS_HOME>/repository/conf/deployment.toml file. The events that need to subscribe to the handler can be listed in subscriptions.

[[event_handler]]
name= "customEventHandler"
subscriptions =["CUSTOM_EVENT"]

Try out the sample application¶

1. Build the custom event handler sample application here.
   • Navigate to event-handler/custom-event-handler directory (cd event-handler/custom-event-handler).
   • Run the mvn clean install command.
2. Copy the generated org.wso2.carbon.identity.customhandler-1.0.0.jar file in the target folder into /repository/components/dropins/ folder.
3. Add following configurations to /repository/conf/deployement.toml file

   [[event_handler]]
   name="customUserRegistration"
   subscriptions=["PRE_ADD_USER","POST_ADD_USER"]

   name: The name of the event handler (Name that return from the getName() method). subscriptions: A list of events that the handler will be subscribed to. In this sample application, we are subscribing to the PRE_ADD_USER and POST_ADD_USER events.
4. Restart the server.

When you want to execute an operation related to an event, publish the event. Then, the handler that is subscribed for the relevant events will be used to execute those events. In the sample configuration given above, the customUserRegistration handler is subscribed to the PRE_ADD_USER, POST_ADD_USER operations.