SPSecurityEventReceiver – The Missing Technical Reference

SPSecurityEventReceiver

Last Updated: July 2, 2015

Recently I needed to know a lot about SharePoint 2013’s SPSecurityEventReceiver, and the MSDN/TechNet information was sparse. So I did what any thorough (obsessive) developer would do and attached all the relevant methods to multiple SPobjects (SPSite, SPWeb, SPList) to see what happens; then I wrote this blog for future reference.

SPSecurityEventReceiver

“Provides methods to trap events that are raised for security. A customer security event receiver class must derive from this class and overrides the methods for the event types it handles.” – MSDN.

That’s all the explanation you get on MSDN. Clearly this does not do justice to the awesomeness of this Event Receiver. A more thorough description would be “[This Server Side and Remote Event Receiver] Provides methods [in 5 main categories: 1. Group Events, 2. User Events, 3. Inheritance Events, 4. Role Assignment Events, and 5. Role Definition Events] to trap events [Adding/Added/Updating/Updated/Deleting/Deleted/Breaking/Broken/Reset/Resetting] that are raised [at the Site Collection or Site level] for security.“.

When working with Event Receivers you need to know two things right up front: 1. What objects can you attach them to and 2. What exactly do they do. To answer the first question refer to the chart below. Through thorough testing (but by no means exhaustive), I have found this to only work on SPSite and SPWeb objects. Note: Testing was only done via Server Side code in Farm Solutions using SPSite, SPWeb, and SPList objects as hosts. It was not tested against SPContentType, SPFile, or SPWorkflow. There is no SPGroup or SPListItem Event Receiver collection to try either. If anyone can show more, please let me know!

Role Definition Events fire when attached to SPWeb only when that object is the root web of a site collection.

The rest of this blog post answers the second question in detail. I have broken out the important methods into five groups/categories.

1. Group Events

  • SPSecurityEventReceiver.GroupAdded
  • SPSecurityEventReceiver.GroupAdding
  • SPSecurityEventReceiver.GroupDeleted
  • SPSecurityEventReceiver.GroupDeleting
  • SPSecurityEventReceiver.GroupUpdated
  • SPSecurityEventReceiver.GroupUpdating

Group Events only occur when you add, update, or delete groups at the site or site collection level from the master Groups list. This is not for events when you add/update/delete them from existing groups or from sites/lists directly. Those are covered via User Events and Role Assignment Events respectively. If you are using a site collection event receiver (SPSite) then anytime you update this list from any site or sub site this will fire. If you are using a site event receiver (SPWeb) then this will only fire if you navigated to this list via that site (even though it updates the same list). It does not fire if attached directly to a list (SPList) and I speculate this will be true for list items (SPListItem). It was not tested against SPContentType, SPFile, or SPWorkflow. There is no SPGroup or SPListItem Event Receiver collection to try either.

Click to enlarge.

To test the Group Events, navigate to the Site Settings page of the root site in the Site Collection then click the People and Groups link in the Users and Permissions section of links. From there click the Groups link in the left navigation menu. You can navigate there directly by using this link (_layouts/15/groups.aspx). On this page you can Add/Update/Delete groups which will cause the event receiver to fire.

2. User Events

  • SPSecurityEventReceiver.GroupUserAdded
  • SPSecurityEventReceiver.GroupUserAdding
  • SPSecurityEventReceiver.GroupUserDeleted
  • SPSecurityEventReceiver.GroupUserDeleting

User Events occur when you add or delete a SharePoint user or SharePoint group or Active Directory (AD) user or AD security group from an existing SharePoint group such as Owners, Members, or Visitors. This happens for all existing groups in the entire site collection (all sites and sub sites) whether local to one list or global to all. If you deploy at the SPWeb level then it will only fire for events on that site or sub site. It does not fire if attached directly to a list (SPList) and I speculate this will be true for list items (SPListItem). It was not tested against SPContentType, SPFile, or SPWorkflow. There is no SPGroup or SPListItem Event Receiver collection to try either.

Click to enlarge.

To test the Group User Events create a new group or navigate to another group contained within the People and Groups (Owners, Members, Visitors, etc.). Add or delete a user or group to/from this group and you will cause the event receiver to fire.

3. Inheritance Events

  • SPSecurityEventReceiver.InheritanceBreaking
  • SPSecurityEventReceiver.InheritanceBroken
  • SPSecurityEventReceiver.InheritanceReset
  • SPSecurityEventReceiver.InheritanceResetting

Inheritance Events occur when you break inheritance or reset inheritance (re-inherit) on lists, libraries, sites, etc. This works on at both the site collection level (SPSite) and site level (SPWeb). It does not fire if attached directly to a list (SPList) and I speculate this will be true for list items (SPListItem). It was not tested against SPContentType, SPFile, or SPWorkflow. There is no SPGroup or SPListItem Event Receiver collection to try either.

Click to enlarge.

To test the Inheritance Events create or navigate to a list or sub-site that inherits permissions from the parent site. Then simply navigate to the permissions page for the list from the list settings page and break (Stop inheriting Permissions) and reset (Delete unique permissions) inheritance.

4. Role Assignment Events

  • SPSecurityEventReceiver.RoleAssignmentAdded
  • SPSecurityEventReceiver.RoleAssignmentAdding
  • SPSecurityEventReceiver.RoleAssignmentDeleted
  • SPSecurityEventReceiver.RoleAssignmentDeleting

Once you break inheritance, for example on a site or list, Role Assignment Events occur when you add or delete users or groups directly via the permissions page for that site/list/etc. This works on at both the site collection level (SPSite) and site level (SPWeb). It does not fire if attached directly to a list (SPList) and I speculate this will be true for list items (SPListItem). It was not tested against SPContentType, SPFile, or SPWorkflow. There is no SPGroup or SPListItem Event Receiver collection to try either.

Click to enlarge.

To test Role Assignment Events use a list or site that you previously created and break permission inheritance. Then click Grant Permissions to add a user or group. You could also select an existing group and remove it (Remove User Permissions).

5. Role Definition Events

  • SPSecurityEventReceiver.RoleDefinitionAdded
  • SPSecurityEventReceiver.RoleDefinitionAdding
  • SPSecurityEventReceiver.RoleDefinitionDeleted
  • SPSecurityEventReceiver.RoleDefinitionDeleting
  • SPSecurityEventReceiver.RoleDefinitionUpdated
  • SPSecurityEventReceiver.RoleDefinitionUpdating

Role Definition Events occur when you add, update, or deleted Role Definitions such as Design, Contribute, or Read. These events only fire when attached at the site collection (SPSite) level or on the root site of the site collection as a web (SPWeb) event receiver. It does not work for any sub site or non root site. Role Definition Events can not be fired from a sub site because these are inherited from the parent site; however, once inheritance is broken they can not be changed either. Also, it does not fire if attached directly to a list (SPList) and I speculate this will be true for list items (SPListItem). It was not tested against SPContentType, SPFile, or SPWorkflow. There is no SPGroup or SPListItem Event Receiver collection to try either.

Click to enlarge.

To test Role Definition Events navigate to the site collection settings page. Click Site permissions then click Permission Levels. On this page add/update/delete Role Definitions to fire the event receiver.

 

UPDATE: RoleAssignmentAdding event receiver in SharePoint 2013 does not show error page with CancelWithError

UPDATE 2: New information added about which SharePoint objects were tested as hosts, which were not, and which can’t be.

Please comment with any incorrect information or to provide updates. I will update this blog post as a reference. Thanks!

Tim Ferro

Trackbacks Comments
  • Liam says:

    Fantastic Pots!!

  • Dylan says:

    I can’t get these events to fire as remote event receivers – is this a known restriction? If so, how would I monitor for security events on a remote SP site, other than polling with GetChanges() (which requires storing credentials in order to authenticate)?

Leave a Comment