Custom Security Trimming for Enterprise Search Results Overview

Article
10/16/2013

Enterprise Search in Microsoft Office SharePoint Server 2007 performs security trimming of search results at query time. The results are trimmed based on the identity of the user submitting the query, by using the security information obtained from the crawler. For more information about how this works, see Enterprise Search Security Model.

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. Enterprise Search provides support for custom security trimming through the ISecurityTrimmer interface.

This topic provides information about the ISecurityTrimmer interface, and describes the following three steps required to use a custom security trimmer for Enterprise Search:

Implementing the ISecurityTrimmer interface
Deploying the custom security trimmer
Registering the custom security trimmer

Implementing the ISecurityTrimmer Interface

To create a custom security trimmer for Enterprise Search results, you must create a component that implements the ISecurityTrimmer interface. This interface is part of the Microsoft.Office.Server.Search.Query namespace, located in Microsoft.Office.Server.Search.dll.

The ISecurityTrimmer interface contains two methods that you must implement: Initialize and CheckAccess.

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 System.Collections.Specialized.NameValueCollection object containing the configuration properties specified for the security trimmer, and a SearchContext object representing the search service of the Shared Services Provider (SSP).

You specify the configuration properties when you register the custom security trimmer (discussed later in this topic).

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 trimmerProperties, SearchContext srchContext)
{
    int intCheckLimit = Convert.ToInt32(trimmerProperties["CheckLimit"]);
}

For a code sample that shows an implementation of the Initialize method, see Step 1: Create the Custom Security Trimmer and Step 3 (Optional): Specify a Configurable Limit on the Number of Crawl URLs Checked in Walkthrough: Using a Custom Security Trimmer for Search Results.

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.

Note

The CheckAccess method can execute multiple times for one search query, depending on the number of results that are passed to the security trimmer.

Two parameters are passed into this method: A System.Collections.Generic.IList object containing the URLs for each content item from the search results that match the crawl rule, and a System.Collections.Generic.IDictionnary object that implementers can use to track information across multiple CheckAccess method calls for the same search query.

The CheckAccess method returns a System.Collections.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 who submitted the query in two ways, depending on the authentication that is configured for the SharePoint site.

If the site is configured to use Windows authentication, the following code retrieves the user name.

string strUser = WindowsIdentity.GetCurrent().Name;

You must also include the following namespace directive.

using System.Security.Principal;

If the site is configured to use Forms or custom authentication, the following code retrieves the user name.

string strUser = HttpContext.Current.User.Identity.Name;

You must also include the following namespace directive.

using System.Web;

Note

You will also need to have a reference in your project for System.Web.

For a code sample that shows a basic implementation of the CheckAccess method, see Step 1: Create the Custom Security Trimmer in Walkthrough: Using a Custom Security Trimmer for Search Results.

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 Enterprise 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. The Query engine then returns this text instead of any results as a response to the search query.

Step 3 (Optional): Specify a Configurable Limit on the Number of Crawl URLs Checked in Walkthrough: Using a Custom Security Trimmer for Search Results contains a sample that demonstrates one way you can implement this.

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: Deploy and Register the Custom Security Trimmer describes steps 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 SSP and crawl rule. If you want to use the security trimmer with multiple SSPs, you must register the security trimmer for each SSP, as well as registering it for each crawl rule it is associated with.

You use the stsadm utility to register the security trimmer, specifying the registersecuritytrimmer operation. The following table describes the parameters that the operation takes.

Parameter	Description
ssp	Required. The name of the SSP; for example, SharedServices1.
id	Required. The security trimmer 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.
typeName	Required. The strong name of the custom security trimmer assembly.
rulepath	Required. The crawl rule for the security trimmer.
configprops	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: Deploy and Register the Custom Security Trimmer. Step 3 (Optional): Specify a Configurable Limit on the Number of Crawl URLs Checked provides a sample that specifies configuration properties for the security trimmer.