In administrative point of view, policy notifications play a major role… It is some kind of a must feature that policy engine supports. In a typical enterprise, authorization policies are defined by a policy administrator who has some knowledge on authorization language such as XACML… Then these policies must be reviewed by the management to apply them in to the run time… PDP policy store is a critical space as all authorization logics in the enterprise manage through it.. Therefore It is important to track the policy store changes by the managers and administrator by using some kind of policy notification mechanism.
Let see, how we can configure the Identity Server supports for policy notifications… Unfortunately there is no any default module that has been shipped to support this. But there are extension points that can be used to plug any notification modules that you wish.
I have written a notification extension and the project can be found here. Following are the things that is supported by this module.
- Email and REST (XML and JSON) notifications are supported. Currently this module can be configured for one notification type. It means it can send either EMAIL or REST XML or REST JSON.
- Notifications can be generated for both PAP policy store and PDP policy store. You want to understand more what is meant by PAP and PDP policy store.. Please read this
- Currently Notification can contain policy identifier, user (the user who perform the action on the policy) and action name (whether the action is -> add, update, delete, enable)
How to configure
Step1. Build this project using Maven 3.0. You can find the built jar file from here. You can do any changes that you wish, in to the source of the project before it is built.
Step2. Copy built jar file i.e org.wso2.carbon.identity.notification.extension-1.0.0.jar in to <IS_HOME>/repository/component/lib directory
Step3. Register notification module using entitlement.properties file which can be found at <IS_HOME>/repository/conf/security directory. You need to configure full qaulified class name of the module and some configuration related to it… Please find sample entitlement.properties file with those configurations from here
Step4. If you are using EMAIL as notification, Please configure email transport details using axis2.xml file which can be found at <IS_HOME>/repository/conf/axis2 directory. Sample configuration would be as follows.
<transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender"> <parameter name="mail.smtp.from">[email protected]</parameter> <parameter name="mail.smtp.user">wso2demomail</parameter> <parameter name="mail.smtp.password">mailpassword</parameter> <parameter name="mail.smtp.host">smtp.gmail.com</parameter> <parameter name="mail.smtp.port">587</parameter> <parameter name="mail.smtp.starttls.enable">true</parameter> <parameter name="mail.smtp.auth">true</parameter> </transportSender>
Notification Module Configuration
There are nine configurations option are available with this module.. You can configure all of them in the entitlement.properties file.
org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.1=notificationType,JSON #org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.1=notificationType,XML #org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.1=notificationType,EMAIL org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.2=ignoreServerVerification,true org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.3=targetUrl,http://localhost:9765/ #org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.3=targetUrl,[email protected] #org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.4=emailTemplateFile,/home/asela/is/wso2is-4.5.0/repository/conf/security/entitlement-email-config #org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.5=emailSubject,Policy Notification #org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.6=roleName, admin #org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.7=pdpNotificationAction, ENABLE;DISABLE;UPDATE;DELETE #org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.8=papNotification,true #org.wso2.carbon.identity.notification.extension.EntitlementNotificationExtension.9=pdpNotification,false
Lets go through more detail on them…
1. notificationType : Type of the notification supported by module whether it is
EMAIL or XML or JSON
2. pdpNotification : PDP notifications. Whether notification must be sent for PDP policy store changes. By default this is enable. But if you want to disable the policy configurations, you can disable it by configuring this property
3. pdpNotificationAction : PDP notification actions. Whether notification must be sent only for some particular changes. There are four actions and you can define multiple actions using semicolon.
ENABLE;DISABLE;UPDATE;DELETE
By default notifications are sent to all type of changes. But if you want to limit it, you can configure this property
4. papNotification : PAP notifications. Whether notification must be sent for PAP policy store changes. By default this disable and you can enable it by configuring this property.
5. targetUrl : Target url.
If XML and JSON notification type is used, Target url is the end point url
If EMAIL notification type is used, Target url is an email address
6. roleName: User group. If EMAIL notification type is used and Target Url is not defined. You can define the user group that email must be sent. (Say: You need to send email to all the member of the Administrator group)
7. ignoreServerVerification : SSL verification configuration, Whether to ignore or validate SSL verification for end point url, if XML and JSON notification types are used.
8. emailTemplateFile : Email Template. If EMAIL notification is used. The subject, body and footer of email must be defined. These can be load from separate fine… There is default format for them, If you want to override it, you can configure location to a template file using this. You need to configure the absolute path for the template file. Sample template file can be found here
9. emailSubject : Subject of the email, If you do not like for the default email support that is used by the module.
Sample Messages
Sample XML notification message.
<PolicyNotification> <PolicyId>TestPolicy</PolicyId> <Action>UPDATE</Action> <User>admin</User> </PolicyNotification>
Sample JSON notification message.
{"PolicyNotification":{"User":"admin","PolicyId":"TestPolicy","Action":"UPDATE"}}
Limitations & Improvements
Some of the limitations that i would like to mention with this module……
- Notification type can not be changed according to policy, user (who update the policy) or any other factors.
- Notification url (or email address) is same for all policy updates or it is also changed according to policy, user (who update the policy) or any other factor ?
- XML policy can not be send as a notification. Once policy Id is there, you can extract the policy later.
You always have freedom to modify this module and use it.. according to your requirement….