Writing a Custom Security Trimmer for SharePoint Server Search
Applies to: SharePoint Server 2010
In this article
Implementing the ISecurityTrimmer2 Interface
Deploying the Custom Security Trimmer Component
Registering the Custom Security Trimmer
You might have certain scenarios, however, in which the built-in security trimming results are not sufficient for your requirements and you need to implement custom security trimming. SharePoint Server search provides support for custom security trimming through the ISecurityTrimmer2 interface.
This topic provides information about the ISecurityTrimmer2 interface, and describes the following steps that are required to use a custom security trimmer for SharePoint Server search:
Implement the ISecurityTrimmer2 interface.
Deploy the custom security trimmer.
Register the custom security trimmer.
Implementing the ISecurityTrimmer2 Interface
To create a custom security trimmer for search results, you must create a component that implements the ISecurityTrimmer2 interface. This interface is part of the Microsoft.Office.Server.Search.Query namespace, located in Microsoft.Office.Server.Search.dll.
The ISecurityTrimmer2 interface contains two methods that you must implement: Initialize(NameValueCollection, SearchServiceApplication) and CheckAccess(IList<String>, IDictionary<String, Object>, IIdentity).
Initialize Method
The Initialize method is executed when the security trimmer is loaded into the worker process, and does not execute again until the worker process is recycled. Two parameters are passed into the method, a NameValueCollection object containing the configuration properties specified for the security trimmer when it is registered with the Search service application, and a SearchServiceApplication object representing the Search service application.
You can access an individual configuration property by using the property name specified when the security trimmer was registered. For example, the following code retrieves the value for a configuration property named CheckLimit.
public void Initialize(NameValueCollection staticProperties, SearchServiceApplication searchApplication)
{
if (staticProperties["CheckLimitProperty"] != null)
{
intCheckLimit = Convert.ToInt32(staticProperties["CheckLimitProperty"]);
}
}
CheckAccess Method
The CheckAccess method is executed at least once each time a search query returns results that match the crawl rule associated with the security trimmer.
Important
The CheckAccess method can execute multiple times for one search query, depending on the number of results that are passed to the security trimmer.
Three parameters are passed into this method: An IList<T> object containing the URLs for each content item from the search results that match the crawl rule, an IDictionary<TKey, TValue> object that implementers can use to track information across multiple CheckAccess method calls for the same search query, and an IIdentity object from which implementers can retrieve the user’s identity from.
The CheckAccess method returns a BitArray object representing an array of true or false values, one for each content item URL in the IList object that is passed as the first parameter of the method. The Query engine uses these values to perform the security trimming of the results. If true, the item is included in the returned results; if false, the item is removed.
When implementing the CheckAccess method, you can use two pieces of information for each item to determine whether to return true or false for the item: the identity of the user who submitted the query, and the URL of the content item.
Retrieving the User Identity
You can retrieve the identity of the user by accessing the thread's current principal, as follows.
IIdentity userIdentity = System.Threading.Thread.CurrentPrincipal.Identity;
You must also include the following namespace directive.
using System.Security.Principal;
You can also retrieve the identity of the user from the CheckAccess method’'s passedUserIdentity parameter.
Performance Implications
A custom security trimmer will impact performance of the Query engine, so you should use a custom trimmer only if the security trimming functionality included with SharePoint Server search does not meet your requirements.
If you must use a custom security trimmer, we recommend that you implement a limit on the number of access checks the trimmer performs for a single query. For example, consider a scenario where the content index contains a million documents, and there is one keyword common to all the documents. A user runs a query on the content index, but that user has access only to the millionth document, not to the others. Without a limit to the number of access checks, the CheckAccess method is called repeatedly until the document that the user has access to is finally returned. In this scenario, performance would be far better if the number of access checks were limited—for example, to 200 checks—and then access checks were stopped and a message was returned to the user requesting that the user refine his or her query for better results.
To do this, you track the number of items checked, and then throw a PluggableAccessCheckException exception. The PluggableAccessCheckException class provides a constructor with a parameter in which you can specify a string containing a message for the user. Note that you can specify a string in the PluggableAccessCheckException constructor, but this string will not be displayed to the end user. Instead, after the exception is thrown by the security trimmer, the trimmerID that caused the exception will be filtered out and the result will be excluded from the search results. Other security trimmed results, if available, will be returned and displayed in the search results user interface.
For a sample that demonstrates one way you can implement this, See Step 3 in Walkthrough: Using a Custom Security Trimmer for SharePoint Server Search Results.
Deploying the Custom Security Trimmer Component
After you create the custom security trimmer, you must deploy it to the global assembly cache on any server in the Query role. Step 2 from Walkthrough: Using a Custom Security Trimmer for SharePoint Server Search Results describes the process for how you can deploy the custom security trimmer to the global assembly cache.
Registering the Custom Security Trimmer
A security trimmer registration is associated with a specific Search service application and crawl rule.
You use the SharePoint 2010 Management Shell to register a custom security trimmer, using the Windows PowerShell cmdlet SPEnterpriseSearchSecurityTrimmer. For more information about using this tool, see Administering Service Applications Using the SharePoint 2010 Management Shell.
The following table describes the parameters that the cmdlet takes.
Table 1. Parameters used by the SPEnterpriseSearchSecurityTrimmer cmdlet
Parameter |
Description |
|---|---|
SearchApplication |
Required. The name of the Search service application, for example "Search Service Application". |
typeName |
Required. The strong name of the custom security trimmer assembly. |
RulePath |
Required. The crawl rule for the security trimmer. |
id |
Required. The security trimmer identifier (ID). This value is unique; if a security trimmer is registered with an ID that is already registered for another security trimmer, the registration for the first trimmer is overwritten with the registration for the second trimmer. |
properties |
Optional. The name-value pairs specifying the configuration properties. Must be in the following format: Name1~Value1~Name2~Value~… |
An example of a basic command for registering a custom security trimmer is shown in Step 2 of Walkthrough: Using a Custom Security Trimmer for SharePoint Server Search Results. Step 3 in the walkthrough provides a sample that specifies configuration properties for the security trimmer.
See Also
Reference
Concepts
Walkthrough: Using a Custom Security Trimmer for SharePoint Server Search Results