WSO2 Identity Provider Event Publishers.
Identity server has facilitated to initiate several events and notifications on a critical identity operations. Initiate an email or an SMS on a critical identity event and update some external system on an identity event can be seen as the most common usage of this approach
Example use cases:
- Send an email at password reset
- Update user account status on an external system at account suspension or account lock
- Send SMS at self registration
Identity server support eventing framework and this framework can be used to trigger some user operations and also publish several events in identity server operations that mentioned in above.
For an example user request to send an email once the user accounts get suspended. Here, user can subscribe to the framework defined user operation (event), ‘POST_ACCOUNT_SUSPENSION’ and publish event notification, ‘email’ through handler.
This document will explain the implementation of such scenarios.
01. WSO2 events
Identity server contains following list of user operation and there are set of events that can emit while operating the user operations. These operations can be used for different notifications. These the user operations available in WSO2 Identity Provider.
- PRE_AUTHENTICATION — Triggered before authenticating a user.
- POST_AUTHENTICATION — Triggered after authenticating a user.
- PRE_ADD_USER — Triggered before adding a new user to the system.
- POST_ADD_USER — Triggered after adding a new user to the system.
- PRE_UPDATE_CREDENTIAL — Triggered before updating user credentials.
- POST_UPDATE_CREDENTIAL — Triggered after updating user credentials.
- PRE_UPDATE_CREDENTIAL_BY_ADMIN — Triggered before updating user credentials by an admin.
- POST_UPDATE_CREDENTIAL_BY_ADMIN — Triggered after updating user credentials by an admin.
- PRE_DELETE_USER — Triggered before deleting a user from the system.
- POST_DELETE_USER — Triggered after deleting a user from the system.
- PRE_SET_USER_CLAIM — Triggered before setting a single user attribute.
- POST_SET_USER_CLAIM — Triggered after setting a single user attribute.
- PRE_SET_USER_CLAIMS — Triggered before setting a set of user attributes as a batch.
- POST_SET_USER_CLAIMS — Triggered after setting a set of user attributes as a batch.
- PRE_GET_USER_CLAIM — Triggered before retrieving a user attribute.
- POST_GET_USER_CLAIM — Triggered after retrieving a user attribute.
- PRE_GET_USER_CLAIMS — Triggered before getting a set of user attributes as a batch.
- POST_GET_USER_CLAIMS — Triggered after getting a set of user attributes as a batch.
- PRE_DELETE_USER_CLAIM — Triggered before deleting a user attribute.
- POST_DELETE_USER_CLAIM — Triggered after deleting a user attribute.
- PRE_DELETE_USER_CLAIMS — Triggered before deleting a set of user attributes as a batch.
- POST_DELETE_USER_CLAIMS — Triggered after deleting a set of user attributes as a batch.
- PRE_ADD_ROLE — Triggered before adding a role.
- POST_ADD_ROLE — Triggered after adding a role.
- PRE_DELETE_ROLE — Triggered before deleting a role.
- POST_DELETE_ROLE — Triggered after deleting a role.
- PRE_UPDATE_ROLE — Triggered before updating a role.
- POST_UPDATE_ROLE — Triggered after updating a role.
- PRE_UPDATE_USER_LIST_OF_ROLE — Triggered before updating the user list of a role.
- POST_UPDATE_USER_LIST_OF_ROLE — Triggered after updating the user list of a role.
- PRE_UPDATE_ROLE_LIST_OF_USER — Triggered before updating the role list of a user.
- POST_UPDATE_ROLE_LIST_OF_USER — Triggered after updating the role list of a user.
- UPDATE_GOVERNANCE_CONFIGURATION — Triggered when updating the governance configurations.
- PRE_ADD_NEW_PASSWORD — Triggered before adding a new password.
- POST_ADD_NEW_PASSWORD — Triggered after adding a new password.
- PRE_SEND_RECOVERY_NOTIFICATION — Triggered before sending recovery notification.
- POST_SEND_RECOVERY_NOTIFICATION — Triggered after sending recovery notification.
- TRIGGER_NOTIFICATION — Triggered when a notification is triggered.
- TRIGGER_SMS_NOTIFICATION — Triggered when an SMS notification is triggered.
- POST_ACCOUNT_SUSPENSION — Triggered after account suspension
- POST_ISSUE_CODE — Triggered after issue auth code
- POST_ISSUE_ACCESS_TOKEN — Triggered after issue access token
- POST_REVOKE_ACESS_TOKEN — Triggered after issue revoke access token
- POST_REVOKE_ACESS_TOKEN_BY_ID — Triggered after issue revoke access token by ID
- POST_REVOKE_CODE_BY_ID — Triggered after revoke coed by id
- POST_REVOKE_CODE — Triggered after revoke code
- POST_REFRESH_TOKEN — Triggered after issue refresh token
1.1 Default event handler and Identity-event.properties file
Default event handler is a handler used to do the operation on publishing events in identity server and Identity-event.properties file which is located in the <IS_HOME>repository/conf/identity folder provide consistency mechanism to send notification. Therefore it is possible to set the different properties and claims in order to read from default notification handler.
- claims
- notification template
- stream
- custom property
02. Subscribe to an event using the default event handler
Add default.notification.sender as a new module in the Identity-event.properties file and subscribe to the event as below.
- module.name.<moduleNo>=default.notification.sender
- default.notification.sender.subscription.<subscriptionNo>=<EventName>
Ex:
- module.name.13=default.notification.sender
- default.notification.sender.subscription.1=POST_ACCOUNT_SUSPENSION
03. Request additional claims.
There are certain set of attributes will be set in user operation. For required additional attributes can be configured in the file, Identity-event.properties
default.notification.sender.subscription.<EventName>.claim.sample_claim=http://wso2.identity/sample/claim
As an example, default send attributes of the POST_ACCOUNT_SUSPENSION event are user-name/userstore-domain and tenant-domain. But let’s assume that other than these attribute user request to send additional attributes such as ‘account lock status’ , we can use this configurations
default.notification.sender.subscription.POST_ACCOUNT_SUSPENSION.claim.accountLocked=http://wso2.org/claims/identity/accountLocked
You can define claim uri, then handler will try to read this claim from the current user store and send as the given attribute name ‘sample_claim’ to the event stream. ‘claim’ is a keyword
04. Configuring an event stream to default notification sender
Stream contains the collection of events. Each event have to subscribe with a stream to publish an event through default event handler.
4.1 Creating new streams
Create the new stream file , <steamName>_<streamVersion>.json with below content and add <IS_HOME>/repository/deployment/server/eventstreams folder.
{ “name”: “steamName”, “version”: “streamVersion” }
As an example, if we need to create a new stream for sms we can create a json file with name ‘id_gov_sms_notify_stream_1.0.0.json’ and add the file content like,
{ “name”: “id_gov_sms_notify_stream”, “version”: “1.0.0” }
4.2 Configuring stream
To configure the stream define it as a property and pass it to the handler level at Identity-event.properties.
default.notification.sender.subscription.<EventName>.stream=streamName:version
As an example, if we need to define a stream to POST_ACCOUNT_SUSPENSION event we can add below line to the identity
default.notification.sender.subscription.POST_ACCOUNT_SUSPENSION.stream=id_gov_sms_notify_stream:1.0.0
4.3 Configuring event output adapter for the event publisher
Event publishers publish events via various transport protocols. These transports are implemented as output event adapters.
Ex:
- Org.wso2.carbon.event.output.adapter.soap
- Org.wso2.carbon.event.output.adapter.email
- Org.wso2.carbon.event.output.adapter.sms
- Org.wso2.carbon.event.output.adapter.http
Publisher xml is the file that contains configuration for event output adapter. Publisher xml contain the stream, event type and adapter configuring data.
Add the create publisher xml at <IS_HOME>/repository/deployment/server/eventpublishers folder
Publisher xml example as below,
4.3.1 Advanced mapping
After entering the adapter properties , Advance mapping (custom mapping) should add under <include> tags.
There are several message format which you want to apply on the published events.
First you have to define advanced mapping format type based on the message you send.
For example, when sending an email you can select Text as the output mapping type and for request an endpoint xml or json type.
Once the advanced mapping format selected, advanced mapping can be done with a template or defined the mapping content (ex: payload or email context ) itself in the publisher.xml
4.3.1.1 Create a template
User can set notification template or use already available templates in product IS. Sample of creating notification template
Once after deciding and set the notification template it should pass to the handler at Identity-event.properties file
default.notification.sender.subscription.<eventName>.notification_template=<notificationTemplateName>
As an example, if we need to define a notification template we can define one of the email templates here. Notification_template is the key word
default.notification.sender.subscription.POST_ACCOUNT_SUSPENSION.notification_template=ADDROLETEMPLATE
05. Publish notification using different publishers
Event publishers are used to publish events via various transport protocols (ex: TCP, SSL/ TCP, HTTP, and HTTPS).These transports are implemented as output event adapters. Let’s see how we can use a couple of events from this approach.
5.1 Sending Email
Email event publisher is used to publish events in XML, JSON or text formats via email transports.
Step 01: Configure mail transport sender
Edit the email address, username, password and other relevant properties in the <PRODUCT_HOME>/repository/conf/output-event-adapters.xml file, to point the mail transport sender which is enabled by default in the product, to a valid SMTP configuration as shown in the example below.
Step 02: Subscribe the event using default notification handler (Chapter 02)
Step 03: Request addition claims (Chapter 03)
Step 04: Subscribe the stream to the event.
Product default stream can use to send emails, id_gov_notify_stream_1.0.0
default.notification.sender.subscription.<EventName>.stream=id_gov_notify_stream:1.0.0
Step 05: Subscribe the soap notification template
Define the notification template as a property and pass it to the handler level at Identity-event.properties.
default.notification.sender.subscription.POST_ADD_ROLE.notification_template=ADDROLETEMPLATE
Step 06: Configure event output adapter
Adapter : Org.wso2.carbon.event.output.adapter.email
Create a publisher xml file with necessary adapter configurations. Add the publisher xml to <IS_HOME>/repository/deployment/server/eventpublishers
As an example,
- Create a publisher xml file with necessary adapter configurations. Add the publisher xml to <IS_HOME>/repository/deployment/server/eventpublishers
- Ex:
The above adapter properties are described below.
- Note: The publisher xml can be created easily with the wso2das email event publisher.
5.2 Sending to an external endpoint.
- Soap
- Json
5.2.1 SOAP
SOAP event publisher sends SOAP events in the xml format via HTTP, HTTPS and local transports.
Step 01: Subscribe the event using default notification handler (Chapter 02)
Step 02: Request addition claims (Chapter 03)
Step 03: Subscribe the stream to the event
Create an xml file with the stream name and version. Add the created stream under <IS_HOME>/repository/deployment/server/eventstreams
As an example, create id_gov_soap_output_notify_stream_1.0.0.json file with the below content.
{ “name”: “id_gov_soap_output_notify_stream”, “version”: “1.0.0” }
Then define the stream as a property and pass it to the handler level at Identity-event.properties.
default.notification.sender.subscription.<EventName>.stream=id_gov_soap_output_notify_stream:1.0.0
Step 04: Subscribe the soap notification template
Define the notification template as a property and pass it to the handler level at Identity-event.properties.
default.notification.sender.subscription.<eventName>.notification_template=soap
Step 05: Configure event output adapter
Adapter : Org.wso2.carbon.event.output.adapter.soap
Create a publisher xml file with necessary adapter configurations. Add the publisher xml to <IS_HOME>/repository/deployment/server/eventpublishers
As an example,
The above adapter properties are described below.
Note: The publisher xml can be created easily with the wso2das soap event publisher
5.2.2 JSON
HTTP event publisher is used to publish events in XML, JSON or text formats via HTTP and HTTPS transports.
Step 01: Subscribe the event using default notification handler (chapter 02)
Step 02: Request addition claims (chapter 03)
Step 03: Subscribe the stream to the event
Create an xml file with the stream name and version. Add the created stream under <IS_HOME>/repository/deployment/server/eventstreams
As an example, create id_gov_http_output_notify_stream_1.0.0.json file with the below content
{ “name”: “id_gov_http_output_notify_stream”, “version”: “1.0.0” }
Then define the stream as a property and pass it to the handler level at Identity-event.properties.
default.notification.sender.subscription.<EventName>.stream=id_gov_http_output_notify_stream:1.0.0
Step 04: Subscribe a notification template
Define the notification template as a property and pass it to the handler level at Identity-event.properties.
default.notification.sender.subscription.<eventName>.notification_template=<templateName>
Step 05: Configure event output adapter
Adapter : Org.wso2.carbon.event.output.adapter.http
Create a publisher xml file with necessary adapter configurations. Add the publisher xml to <IS_HOME>/repository/deployment/server/eventpublishers
As an example,
The above adapter properties are described below.
Static adapter properties
Dynamic adapter properties
Note: The publisher xml can be created easily with the wso2das http event publisher.
5.2.3 Test the scenario
If your testing this scenario main problem is to how to verify whether the given HTTP endpoint as been hit after triggering the event and how to get the response of it. Simply Webhook.site allows to test the HTTP request.
