Extreme Sharepoint

In my previous post I demonstrated custom security trimming in Moss (SharePoint 2007). This post focuses on implementing custom security trimming in SharePoint 2010.

In general, SharePoint 2010 provides security trimming out-of-box for the content which is indexed from WSS 3.0, SharePoint 2010, windows file system or any location where objects or files have ACL associated with them. An ACL (access control list) is a list of permissions attached to a file or folder and it determines which users are granted access to files and what operations are allowed on given files.

SharePoint stores the ACL information while crawling the content. When a user performs search, this information is used to filter search results at run time. However, this is not the case for every type of content …like non-SharePoint websites. For some cases, like one here, It does not happen even if  the content is in SharePoint.

For such  extreme ( sorry for overloading the term many times ) cases where specific business rules need to be applied before search results are displayed to user, SharePoint 2010 provides ISecurityTrimmer2 Interface (I am not sure why it is 2 and not 1) defined in Microsoft.Office.Server.Search.Query namespace.

Just like ISecurityTrimmer in Moss, following three steps required to use a custom security trimmer for SharePoint 2010 Enterprise Search:

1. Implement the ISecurityTrimmer2 interface
2. Deploy the custom security trimmer
3. Register the custom security trimmer
4. Debug the custom security trimmer(optional)

Implementing the ISecurityTrimmer2 interface

In VS2010, Create an empty SharePoint project as a farm solution and add reference to

• Microsoft.Office.Server.Search.dll (14\ISAPI\Microsoft.Office.Server.Search.dll)
• Microsoft.IdentityModel.dll (C:\Program Files\Reference Assemblies\Microsoft\Windows Identity Foundation\v3.5\Microsoft.IdentityModel.dll) [Note: This reference is only required in case of Claims Mode Authentication.  By default, SharePoint 2010 site have Classic Mode Authentication (Integrated Windows Authentication) and so you will not need it (most probably).Also, You should have Windows Identity Foundation SDK installed. Download and install WindowsIdentityFoundation-SDK-3.5.msi  .Take care to download V3.5 and not V4]

Create a custom class and implement ISecurityTrimmer2. There are two methods in the interface we need to implement:

1.  ISecurityTrimmer2.Initialize () : In this method, we can provide or retrieve values for configuration properties for the trimmer.

Two parameters which are passed into the method are:

• NameValueCollection Object: It contains the properties configured for the security trimmer when it is registered (using stsadm) with the Search service application.
• SearchServiceApplication Object: It is the Search service application with which security trimmer is registered.

In ISecurityTrimmer2.Initialize () method, we can retrieve values for some properties which were configured at the time of registering the security trimmer using stsadm. For example, to optimize performance, you may want to limit the amount of crawled urls to be processed by your custom security trimmer. For that we need to retrieve CheckLimitProperty. Below is the code you write to do that.

           //to provide default configuration limit for search results on which security trimming is applied
            private int intResultsCheckLimit = 150;
            public void Initialize(NameValueCollection trimmerProperties, SearchServiceApplication searchApplication)
            {
                //retrieve the value of CheckLimitProperty if it is configured while registering the trimmer using stsadm and use it if found.
                if (trimmerProperties["CheckLimitProperty"] != null)
                {
                    intResultsCheckLimit = Convert.ToInt32(trimmerProperties["CheckLimitProperty"]);
                }
            }

2.  ISecurityTrimmer2.CheckAccess() :  This is  the  method where security trimming is applied to the search results.  The CheckAccess()  can execute multiple times for one search query, depending on the number of results that are passed to the security trimmer.

This method has some differences between Moss and SharePoint 2010. In SharePoint 2010 we get an IIdentity and in MOSS we  use WindowsIdentity.GetCurrent()(For Windows Authentication) or HttpContext.Current.User (For Forms Authentication).

 Three parameters which are passed into the method are:

• IList<String> documentCrawlUrls : It is collection of URLs for each content item from the search results that match the crawl rule.

• IDictionary<String, Object> sessionProperties : This object is the collection of configuration properties and it is used (by developers like us) to track or preserve custom information across multiple CheckAccess() method calls for the same search query

• IIdentity passedUserIdentity : The identity of the user who issued the query. We can also use IIdentity as mentioned instead of passedUserIdentity parameter : IIdentity userIdentity = System.Threading.Thread.CurrentPrincipal.Identity;

This ISecurityTrimmer2.CheckAccess() method returns a BitArray which is a collection of bit values,  represented as boolean, where true indicates that the bit is on (1) and false indicates the bit is off (0).

If the bit has a value of 1, the corresponding crawl URL is displayed in the Search results; otherwise the crawl URL is not be displayed in the Search results.

For a content source that is configured to crawl external websites using http protocol, the documentCrawlUrl  is the exact url of the a page crawled.

For a content source that is configured to crawl SharePoint sites, the documentCrawlUrl may take below forms depending on the protocol:

• sps://wssv2site/site$$$category/bucketid=6/itemid={7c436fba-8618-4558-a3d0-709f29fb3d8e} [ This is generally when a WSS 2.0 site is crawled]
• sts3://spsite/siteurl=/siteid={f208bff2-a0dd-4f8d-9dac-9bb3dceb4114}/weburl=/webid={567c4e3d-0c7b-450b-bfc9-f8a4ee60bc94}/listid={bf8a9b92-3bdb-483b-91a5-76b63de5a575}/folderurl=/itemid=182 [ This is when a SP2010 site is crawled]

It is important that we know the format of documentCrawlUrls because we will use that information in our security trimming logic, like I did here for draft items

public BitArray CheckAccess(IList<String> documentCrawlUrls, IDictionary<String, Object> sessionProperties, IIdentity passedUserIdentity)
            {
                BitArray retArray = new BitArray(documentCrawlUrls.Count);
                IIdentity userIdentity = System.Threading.Thread.CurrentPrincipal.Identity;

//For claims, use IClaimsIdentity. It is defined in Microsoft.IdentityModel.Claims; 
//IClaimsIdentity claimsIdentity = (IClaimsIdentity)passedUserIdentity

                for (int x = 0; x < documentCrawlUrls.Count; x++)
                {
                    string currentDocUrl = documentCrawlUrls[x];
                    /* Add code here to check if user associated with userIdentity can access documentCrawlUrls[x]. If so: retArray[x] = true; If not: retArray[x] = false; */
                }
                return retArray;
            }

Deploy and Register the Custom Security Trimmer

1)      Deploy the assembly to GAC. [Note: If you have multiple Web front-end (WFE) servers, you must deploy to GAC on all WFEs].

2)      Creating a Crawl Rule for the Custom Security Trimmer.

Before you register the custom security trimmer, we need to create the crawl rule for the content that the custom security trimmer applies to.To create the crawl rule Open SharePoint 2010 Central Administration, and then navigate to the Application Management page.

3)      Register the Custom Security Trimmer

Using PowerShell :In SharePoint 2010 Management Shell, run below command (Replace class , assembly,rulepath  and Search Service Application details with yours)

New-SPEnterpriseSearchSecurityTrimmer -SearchApplication "Search Service Application 1" -typeName "SP2010.Samples.CustomSharepoint2010SecurityTrimmer, SP2010.Samples, Version=1.0.0.0, Culture=neutral, PublicKeyToken=f4496ec7e0f80a75" -RulePath http://wssv2site/* -id 1
//Code

Using PluggableSecurityTrimmerManager : Using PluggableSecurityTrimmerManager Class, we can programmatically access already registered security trimmers and also we can register new trimmers.

4)       Do a full crawl the Content Source. The content source in this example is configured to crawl external web sites as below.

The complete code will look like :

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.Office.Server.Search.Query;
using Microsoft.Office.Server.Search.Administration;
using System.Collections.Specialized;
using System.Collections;
using System.Security.Principal;
using Microsoft.IdentityModel.Claims;

namespace SP2010.Samples.CustomSharepoint2010SecurityTrimmer
{
    public  class CustomSharepoint2010SecurityTrimmer : ISecurityTrimmer2
        {
            //to provide default configuration limit for search results on which security trimming is applied
            private int intResultsCheckLimit = 150;

            public void Initialize(NameValueCollection trimmerProperties, SearchServiceApplication searchApplication)
            {

                //retrieve the value of CheckLimitProperty if it is configured while registering the trimmer using stsadm and use it if found.
                if (trimmerProperties["CheckLimitProperty"] != null)
                {
                    intResultsCheckLimit = Convert.ToInt32(trimmerProperties["CheckLimitProperty"]);
                }
            }

            public BitArray CheckAccess(IList<String> documentCrawlUrls, IDictionary<String, Object> sessionProperties, IIdentity passedUserIdentity)
            {
                BitArray retArray = new BitArray(documentCrawlUrls.Count);

                //Check if the search results obtained are under limit (150 or that from trimmerProperties["CheckLimitProperty"]) when the current search query is executed
                if (!this.CheckLimit(sessionProperties, documentCrawlUrls.Count))
                {
                    throw (new PluggableAccessCheckException("Reached Limit!This Security trimmer will not be applied"));
                }

                IIdentity userIdentity = System.Threading.Thread.CurrentPrincipal.Identity;

 //For claims, use IClaimsIdentity. It is defined in Microsoft.IdentityModel.Claims; 
 //IClaimsIdentity claimsIdentity = (IClaimsIdentity)passedUserIdentity

                for (int x = 0; x < documentCrawlUrls.Count; x++)
                {
                    string currentDocUrl = documentCrawlUrls[x];
                    /* Add code here to check if user associated with userIdentity can access document 
 or page with url documentCrawlUrls[x]. If so: retArray[x] = true; If not: retArray[x] = false; */
                }
                return retArray;
            }

            private bool CheckLimit(IDictionary<String, Object> sessionProperties, int documentCrawlUrlsCount)
            {
                Object currentCount;
                //Use of sessionproperties to store and preserve checkcount across multiple CheckAcess() calls
                sessionProperties.TryGetValue("currentCheckCount", out currentCount);
                if (currentCount == null)
                {
                    sessionProperties["currentCheckCount"] = documentCrawlUrlsCount;
                    return (true);
                }
                int currentCountInt = Convert.ToInt32(currentCount);
                currentCountInt += documentCrawlUrlsCount;

                sessionProperties["currentCheckCount"] = currentCountInt;
                if (currentCountInt <= intResultsCheckLimit)
                {
                    return true;
                }
                else
                {
                    return false;
                }
            }
        }

}

Security trimmer  or ISecurityTrimmer2 account :

Got to Central Administration >Configure service accounts.

Check the account for “Service Application Pool – SharePoint Web Services Default”. This pool hosts the Search Service Application. It is not recommended not to manage this app pool account yourself because it hosts other services as well which may get affected.

Important to read : Performance Implications of implementing custom security trimmer

A custom security trimmer has affect on performance of the Search, so we should go for it only if the out-of-box security trimming functionality does not meet our requirements.

Also, It is recommend to  limit the number of access checks the trimmer performs for a single query. Without a limit, the CheckAccess method is called many times until the document that the user has access to is returned. In this scenario, performance would be much better if the number of access checks are limited(to 150 for example). The access checks are stopped after the limit is exceeded and a message is presented to the user to refine his query for better results.

We can track the number of items checked and  throw a PluggableAccessCheckException exception if limit exceeds.We can pass a string  message  for the user to the constructor of the PluggableAccessCheckException class. The Search then returns this text instead of any results in response.

Technorati Tags : SharePoint 2010 Search