Writing a Custom Event Handler¶
The WSO2 Identity Server 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.
- Publish the
PRE_ADD_USER
event — The subscribed handlers will be executed for the pre-add user event. - Execute the
AddUser
operation — The user will be persisted to the user store (LDAP or JBDC user store). - 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.
PRE_AUTHENTICATION
POST_AUTHENTICATION
PRE_SET_USER_CLAIMS
POST_SET_USER_CLAIMS
PRE_ADD_USER
POST_ADD_USER
PRE_UPDATE_CREDENTIAL
POST_UPDATE_CREDENTIAL
PRE_UPDATE_CREDENTIAL_BY_ADMIN
POST_UPDATE_CREDENTIAL_BY_ADMIN
PRE_DELETE_USER
POST_DELETE_USER
PRE_SET_USER_CLAIM
PRE_GET_USER_CLAIM
POST_GET_USER_CLAIMS
POST_GET_USER_CLAIM
POST_SET_USER_CLAIM
PRE_DELETE_USER_CLAIMS
POST_DELETE_USER_CLAIMS
PRE_DELETE_USER_CLAIM
POST_DELETE_USER_CLAIM
PRE_ADD_ROLE
POST_ADD_ROLE
PRE_DELETE_ROLE
POST_DELETE_ROLE
PRE_UPDATE_ROLE
POST_UPDATE_ROLE
PRE_UPDATE_USER_LIST_OF_ROLE
POST_UPDATE_USER_LIST_OF_ROLE
PRE_UPDATE_ROLE_LIST_OF_USER
POST_UPDATE_ROLE_LIST_OF_USER
UPDATE_GOVERNANCE_CONFIGURATION
TRIGGER_NOTIFICATION
Writing an event handler¶
To write a new event handler, you must extend the org.wso2.carbon.identity.event.handler.AbstractEventHandler
.
-
Override the
getName()
method to set the name for the event handler and thegetPriority()
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 "emailSender"; } @Override public int getPriority(MessageContext messageContext) { return 50; }
-
To execute the expected operation, override the
handleEvent()
method. Theevent.getEventProperties()
method can be used to get the parameters related to the user operations.@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);
Registering 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) {
...
}
Configuring 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= "emailSender"
subscriptions =["POST_ADD_USER"]
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 emailSender
handler is subscribed to the POST_ADD_USER
operation.
Info
The following sample event handlers are available with WSO2 Identity Server.