Document level security
Document level security (DLS) allows you to provide search results that are filtered to include only documents that the connected user is allowed to see.
Document level security requirements
For document level security to be implemented within a search you require the following:
-
the search results must be proxied via a CMS that is responsible for authenticating the user and supplying the user’s keys when calling the search.
-
the content items must include a security metadata field containing the lock strings that apply to the document, and this metadata field must be mapped to a security metadata class within Funnelback.
-
the search package and data sources must have authentication enabled and be configured with a user to key mapper.
-
the data sources must also have a locks to keys matcher configured.
Search package configuration
The search package that hosts your search must be configured with the following:
-
Enable authentication: in the search package configuration, set the configuration key:
ui.modern.authentication=true. -
Set the user to key mapper: in the search package configuration, set the configuration key:
security.earlybinding.user-to-key-mapper=Meta. This configures the search package to pass through the user keys to the component data sources when looking up the results.
In addition access to the search package should be locked down once testing of any DLS setup is completed:
-
Consider using
access_restrictionto restrict search requests to specific IP addresses. -
Use the Access restriction to search results plugin to require a pre-shared secret to be included when calling the search results.
Data source configuration
Each data source that contains secure content within your secure search package must be configured with the following:
-
Enable authentication: in the data source configuration, set the configuration key:
ui.modern.authentication=true. -
Set the user to key mapper: in the data source configuration, set the configuration key:
security.earlybinding.user-to-key-mapper=Portal. This configures the data source to read the user’s keys from theuserkeysparameter, which was supplied to the search package. -
Set the locks to keys matcher: in the data source configuration, set the configuration key:
security.earlybinding.locks-keys-matcher.name=secBoolExpr. This configures the data source to use boolean lock strings. -
*Set the following in your indexer options:
-lock_string_mod_mode=raw
Configuring the security metadata
Items that are being secured via DLS require a metadata field that specifies the security lock string that applies to the document. The value should be a boolean expression lock string, as supported by the plugin.
e.g. This item can be viewed by staff OR students OR management, and a userkeys string containing any of these values will be permitted access to the document (e.g. userkeys=staff,students,supervisors)
<meta name="groups" content="staff|students|management"/>or
<groups>staff|students|management</group>| Security metadata for documents can also be supplied using external metadata. This is especially useful for binary documents such as PDFs. |
This metadata field needs to be mapped within the data source metadata mappings, as a document permissions type metadata field. Selecting the field source is the same as for any other metadata mapping.
Limitations
When using document level security the following limitations apply:
-
Access to the cached version of documents via the cache controller is disabled.
-
A single lock string per-document is supported. If a document within a secured data source is missing a lock string then access to that document will be blocked for all users.
Disabling document level security
Disabling early-binding document level security can be achieved in two ways:
Method 1: Keep the lock strings in the data source, but use a user/key mapper plugin that always returns a master key that matches every document. To do so:
-
Set
security.earlybinding.locks-keys-matcher.nameto an empty value so that the query processors use the default matching algorithm. -
Set
security.earlybinding.user-to-key-mapperto `Master `to always return a user key that should match every document.
Method 2: Remove the lock strings from the data source. To do so:
-
Remove the document permissions metadata class from the data source using the metadata customization tool in the search dashboard.
-
Re-index the data source.
-
Remove, or set
security.earlybinding.locks-keys-matcher.nameandsecurity.earlybinding.user-to-key-mapperto blank values.
Translucent document level security
Translucent DLS (document level security) extends the document level security concept by adding a mode where some metadata about protected documents can be displayed to users who do not have access to the document.
This is useful when you want users to know that protected information exists that is relevant to the search, but the user will need to request access to the document.
As translucent DLS reveals some information it should only be used when all authorized users are trusted.
Translucent DLS can only be enabled on searches which have document level security enabled.
To enable translucent DLS add the following query processor option in either the results page or search package configuration.
query_processor_options= -translucent_DLS=on <other query processor options>
Once enabled, documents that match the user’s query that can not be viewed by the user will be returned in the result in the usual ranking order, with all revealing information removed. This includes not showing the document title, summary, and document links. To make these results useful, translucent metadata should be configured.
Translucent metadata
When translucent DLS is used, the search user needs a way to request access to a document they cannot see. To achieve this, specific metadata fields can be marked as translucent in the query processor options. For example, to reveal the owner and doctitle metadata of the document set:
-translucent_DLS_fields=[owner,doctitle]
The list of summary fields (-SF) to display in the query processor options still controls which fields can be displayed; however, the fields returned for translucent records will only list the field defined in the -translucent_DLS_fields option when a user does not have access to the document.
Collapsing with translucent DLS
Result collapsing can be used when translucent DLS is activated. Documents that the user can not see can only be collapsed if the collapsing signature contains only fields set in -translucent_DLS_fields=. If the signature contains other fields, including special fields such as $, then only documents that the user can see will be collapsed.