8.1How saved filters work

What a saved filter contains

When the filter runs, the object type is applied on top of the LDAP filter. A filter of (department=Finance) with the object type User returns only user objects in Finance; the same filter with Generic returns every kind of object whose department is Finance.

Saved filters are shared, and run against the current directory

Saved filters belong to the installation, not to one person and not to one directory connection:

• Everyone sees every saved filter. The list shows all saved filters created by anyone, provided the viewer holds the list permission.
• Anyone with the update permission can edit any filter, whoever created it. This lets a team maintain filters created by a colleague who has left, or by the service account behind an API key.
• Only the creator can delete a filter. Deleting cannot be undone, so it stays with the person who made it.
• A filter runs against the directory you are working in. In the console that is the directory selected in your workspace; for an API key or agent it is the connection that credential is bound to. The same filter can therefore be run against different domains.

Important: Because a filter is not tied to a connection, a stored Base DN names a location in one particular domain. Running a filter whose base DN does not exist in the current directory fails with a "search base not found" error. Leave Base DN empty when a filter should work in every directory.

Permissions

In the permission editor these appear under the Saved searches resource ("Reusable directory queries shared across the team.").

Running a filter is a separate permission from seeing it on purpose: running reads the directory, so knowing that a filter exists does not imply being allowed to see what it returns. The predefined read-oriented role templates include list, read and execute; the editing permissions come with the administrative templates. See Chapter 11, Users, roles and permissions.

Licence

Running a saved filter reads the directory and therefore needs an active licence. On an unlicensed installation a run is refused with HTTP 403 and the error code License.NotActivated, and the console hides the LDAP Filters screen. No specific licence module is needed beyond an active licence, except that running a filter from an AI agent also needs the MCP module on the licence (see Chapter 13). Listing, creating, editing and deleting filters over the REST API do not check the licence. See Chapter 19, Licence, updates and backups.

Security checks on filters

Some directory attributes hold secrets, for example local administrator passwords managed by LAPS or managed service account passwords. The platform refuses to read them, and it also refuses a filter that tests them: a clause such as (ms-Mcs-AdmPwd>=M) would otherwise let a caller work out a password one comparison at a time, even without being able to read it. This check is made when the filter runs, before anything reaches the directory: a filter naming such an attribute, or an attribute the check cannot identify (for example a bare OID), is refused with HTTP 403 and the error code AD.Attributes.ReadForbidden. The same applies to an attribute that an administrator has blocked with an attribute policy for the directory (see Chapter 10, Operation policies, attribute policies and agent supervision): a filter testing it is refused with AD.Attributes.ReadForbidden, so a filter that worked before the rule was added stops working. A filter that cannot be parsed is refused as invalid (HTTP 400). Saving such a filter is not refused, so test a new filter by running it.

The platform also checks the filter's basic shape when you save it: