WSO2 Identity Server Eventing Framework

WSO2 Identity Server 5.3.0 onwards support the eventing framework which can be used to trigger some events such as user operations. Also, the eventing framework supports handlers which can be used to do some operations based on the published events.

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

What is an Event Handler?

Event handlers are used to do some operation based on the published events.

Example

Send an email after a user addition.

Following sequence of operations are executed while adding a user.

1. Publish PRE_ADD_USER event. — The subscribed handlers will be executed for the pre-add user event.

2. Execute AddUser operation. — The user will be persisted in the user store. (LDAP or JBDC user store)

3. Publish POST_ADD_USER event. — The subscribed handlers will be executed for the post-add user event

So, we can send the email through an event handler which is subscribed to POST_ADD_USER event.

How to write a sample Event Handler?

A sample event handler can be created by extending the org.wso2.carbon.identity.event.handler.AbstractEventHandler.

1. Need to override getName() method to set the name for the event handler.

public String getName() {
    return "emailSender";
}

2. getPriority() method can be used to set the priory of the event handler. So, the handlers will be executed based on the priority.

@Override
public int getPriority(MessageContext messageContext) {
    return 50;
}

3. handleEvent() method can be used to do the actual operation. The parameters related to the user operations can be taken from the event.getEventProperties() method.

Need to do the operation based on those parameters. Ex. sending an email.

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

4. Register the event handler.

The event handler needs to register 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) {
       ...
    }

5. The events which need to subscribe to the handler can be configured through {wso2is-home}/repository/conf/identity/identity-event.properties file.

module.name.10=emailSender
emailSender.subscription.1=PRE_AUTHENTICATION
emailSender.subscription.2=POST_AUTHENTICATION
emailSender.subscription.3=PRE_SET_USER_CLAIMS
emailSender.subscription.4=POST_SET_USER_CLAIMS

This means the emailSender handler is subscribed for PRE_AUTHENTICATION, POST_AUTHENTICATION, PRE_SET_USER_CLAIMS and POST_SET_USER_CLAIMS events.

Inbuilt sample Event handlers in WSO2 Identity Server.

1. UserEmailVerificationHandler [1]
2. AccountConfirmationValidationHandler [2]
3. AdminForcedPasswordResetHandler [3]
4. UserSelfRegistrationHandler [4]
5. PasswordHistoryValidationHandler [5]
6. PasswordPolicyValidationHandler [6]
7. AccountSuspensionNotificationHandler [7]

Reference

[1] https://github.com/wso2-extensions/identity-governance/blob/master/components/org.wso2.carbon.identity.recovery/src/main/java/org/wso2/carbon/identity/recovery/handler/UserEmailVerificationHandler.java

[2] https://github.com/wso2-extensions/identity-governance/blob/master/components/org.wso2.carbon.identity.recovery/src/main/java/org/wso2/carbon/identity/recovery/handler/AccountConfirmationValidationHandler.java

[3] https://github.com/wso2-extensions/identity-governance/blob/master/components/org.wso2.carbon.identity.recovery/src/main/java/org/wso2/carbon/identity/recovery/handler/AdminForcedPasswordResetHandler.java

[4] https://github.com/wso2-extensions/identity-governance/blob/master/components/org.wso2.carbon.identity.recovery/src/main/java/org/wso2/carbon/identity/recovery/handler/UserSelfRegistrationHandler.java

[5] https://github.com/wso2-extensions/identity-governance/blob/master/components/org.wso2.carbon.identity.password.history/src/main/java/org/wso2/carbon/identity/password/history/handler/PasswordHistoryValidationHandler.java

[6] https://github.com/wso2-extensions/identity-governance/blob/master/components/org.wso2.carbon.identity.password.policy/src/main/java/org/wso2/carbon/identity/password/policy/handler/PasswordPolicyValidationHandler.java

[7] https://github.com/wso2-extensions/identity-governance/blob/master/components/org.wso2.carbon.identity.account.suspension.notification.task/src/main/java/org/wso2/carbon/identity/account/suspension/notification/task/handler/AccountSuspensionNotificationHandler.java