This section describes the document level security features available in Funnelback. Document level security provides the capability to control which documents are visible to users using the Funnelback search engine at the level of the individual document, rather than the more general collection level security. Enabling document level security will allow repositories with complex security restrictions to be easily searched using a single interface available to a wide range of users.
Please note that when using document level security, access to the cached version of documents via the cache controller is disabled.
Timing of security binding
Funnelback includes security check functions which operate on access control information recorded at the time that each document was gathered (sometimes called early-binding security). This 'early binding' approach provides a good level of search speed while ensuring that permissions are regularly updated when documents are re-gathered to account for document changes.
Earlier version of Funnelback also provided a 'late binding' approach whereby the underlying repository was checked for user permissions at the time of the search query, rather than at the time of gathering. While this approach ensures that access control changes are reflected more rapidly in the search results, there was a large performance cost to performing these checks, hence they are no longer supported by default. Custom security check plugins could be developed to implement such late-binding (or hybrid) security checks if such checks were needed.
Details on security binding
When document level security is enabled security information of each document is embedded in the collection.
When the origin repository is gathered Funnelback collects the security information of each document, the lock strings. When a user performs a search Funnelback collects its credentials, the user keys, and the query processor tries to match those keys against the lock string embedded in the documents, for each document matching the query.
The user keys are mapped to a metadata class like any other metadata, using the content flag 4 in metamap.cfg or xml.cfg (This is automatically done when the collection is created). For example for TRIM collections the following mapping should be used:
The metadata containing the lock string as well as the format of the lock string itself will vary depending on the collection type and remote repository type. Please see the per-collection instruction for details.
Fetching user keys: The type of user credentials, the way to fetch them and to map them into user keys is configured in security.earlybinding.user-to-key-mapper and will depend on the remote repository type. Various user key mappers plugins are provided in the $SEARCH_HOME/share/security_plugins/ folder.
Matching user keys with lock strings: To find if a user is authorized to see a specific document the query processor tries to match the user keys against the document lock string. The default matching algorithm checks that the document lock string contains at least one of the user keys. The algorithm can be changed by specifying a plugin name in security.earlybinding.locks-keys-matcher.name. Various plugins are provided in $SEARCH_HOME/lib/plugins/.
Available collection types
The following collection types support document level security:
- Using document level security with NTFS filecopy collections
- Using document level security with TRIMPush collections
- Using document level security with Meta collections
Authentication and delegation
Users must be authenticated for Document Level Security to function. Funnelback currently supports document level security:
- Within a Windows Active Directory domain (see the ui.modern.authentication setting)
- With some external system (such as a portal or CMS) authenticating users prior to reaching Funnelback.
Where Active Directory is used, Windows authentication and trust delegation must be working properly for the Funnelback server. Having authentication and trust delegation working on the Windows Domain is a pre-requisite for configuring Document Level Security.
Switching off document level security
Disabing early-binding document level security can be achieved in two ways:
Method 1: Keep the lock strings in the collection, but use a user key mapper plugin that always returns a master key matching every documents. To do so:
- Set security.earlybinding.locks-keys-matcher.name to blank so that the query processors use the default matching algorithm.
- Set security.earlybinding.user-to-key-mapper to Master to always return a user key that should match every document.
Note: This will not work with NTFS filecopy collection. To disable early-binding security on this collection type you need to apply the second method. This will also not work with collections types that use a custom keys / lock matching algorithm (as opposite to the default one) such as TRIM and TRIMPush collections.
Method 2: Remove the lock strings from the collection. To do so:
- Remove the lock string mapping of type 4 from metamap.cfg.
- Re-index the collection.
- Set security.earlybinding.locks-keys-matcher.name and security.earlybinding.user-to-key-mapper to blank.
- Editing Collections
- Windows authentication and trust delegation