Business Data Catalog Security Trimmer

Enterprise Search in Microsoft Office SharePoint Server 2007 in Microsoft Office SharePoint Server 2007 performs query-time security trimming of search results using the security information obtained at crawl time. However, there may be scenarios where this may not be sufficient, for example, when back-end applications cannot provide security information at crawl time or when you need up-to-date security information and it is not practical to crawl each time. To address this scenario, the Enterprise Search Query Processing engine provides a framework for plugging in dynamic query time security trimming modules where the specific results of a single user query can be security-trimmed before being displayed in Search Results.

The Business Data Catalog implements the CheckAccess interface to provide built-in support for per-entity instance security trimming, or entity instance-level security.

The Business Data Catalog Security Trimmer allows custom security trimming of entity instances (search documents) that have been indexed by the Business Data Catalog before they are returned to the user. It trims the result set (containing entity instances) at execution time based on the current user's rights on the back-end data, using the logic in the back-end application to determine the user's rights. It is assumed that the actual back-end application will provide a public method to check the current user's permissions for one or more entity instances. The input parameters of the method should accept the IDs of the EntityInstance objects to be checked and the output parameter should return the access rights for the current user as a corresponding array of long integers (or some value that can be converted to a long integer).

After such an API is available, authors of the Business Data Catalog metadata can define a MethodInstanceType called AccessChecker in the application definition file, and map it to the back-end API in much the same way as for Finder, SpecificFinder, and so on. After an AccessChecker method instance is available, the Business Data Catalog security trimmer can use it to determine the user's rights via the CheckAccess method.

The Business Data Catalog Security Trimmer executes CheckAccess method each time the Query engine returns search results that match the crawl rule the Business Data Catalog security trimmer is associated with. When the Entity.CheckAccess method is called, the Business Data Catalog, in turn, executes the back-end API described by the AccessChecker method instance registered for that entity. The back-end API returns the rights the current user has on the entity instance or instances. This is relayed back to the Entity.CheckAccess method, and finally to the security trimmer, which uses this information to trim the results before displaying the results to the user.

Important

For a complete walkthrough, see Walkthrough: Using the Business Data Catalog Security Trimmer to Trim Search Results.

Internal Details

The Business Data Catalog Security Trimmer maps the Microsoft.Office.Server.Search.Query.ISecurityTrimmer.CheckAccess(System.Collections.Generic.IList{System.String},System.Collections.Generic.IDictionary{System.String,System.Object}) method to the Microsoft.Office.Server.ApplicationRegistry.MetadataModel.Entity.CheckAccess(System.Object[],Microsoft.Office.Server.ApplicationRegistry.MetadataModel.LobSystemInstance) method by parsing the URLs supplied by the Query processor to the Entity.CheckAccess method after determining the LobSystem object and entities each URL comes from.

However, because ISecurityTrimmer.CheckAccess must return an array of "Yes" or "No" values, and because the Entity.CheckAccess method returns an array of rights vectors, the Business Data Catalog Security Trimmer provides a way to convert a rights vector into a Yes or a No by reading a special property on the Entity object called DisplaySearchResultRightsMaskPropertyName.

Finally, the Business Data Catalog Security Trimmer tries to limit the number of access checks it performs for a single call to the Search Query object model. For example, if the index contains a million documents, and there is a single keyword common to all the documents, and the user runs such a query, and user has access only to the millionth document and not to all the others, the Query Processor continues calling Entity.CheckAccess until all the documents are tested. This can take a long time. So the Business Data Catalog trimmer tracks how many documents are looked at via a custom configurable limit (default is 100). If the limit is exceeded, it throws an exception that is displayed as a message to the end user requesting that the query be narrowed in scope.

See Also

Concepts

Walkthrough: Using the Business Data Catalog Security Trimmer to Trim Search Results
AccessChecker Samples