Skip to content

Publishing a SearchKit display

Alpha

The class names below are the ones in the current code. They may still change before the first stable release; any change will be listed in the Release Notes.

A tool runs every API call with checkPermissions on, so CiviCRM's own security is the ceiling: civicrm_mcp never shows anyone more than CiviCRM itself would. There is exactly one way for a tool to show a user more than their own ACLs, and it is CiviCRM's own: a SearchKit display set to bypass ACLs, reached through a form the user may open. Adding another is a change to this rule, not to one tool. Security and permissions describes it for site administrators. This page is the rule for anyone writing or reviewing a tool pack.

An extension can still write a tool of its own that turns permission checks off. civicrm_mcp cannot stop that, but it is outside this rule: the extension's authors answer for it, and a site should review it as it would any code that bypasses CiviCRM's permissions.

Published SearchKit displays

Running a SearchKit display that bypasses ACLs (acl_bypass) is the one path, however a tool does it. Do it only through Civi\Mcp\Tools\PublishedDisplay, which offers one display as a tool and runs SearchDisplay.run with checkPermissions on, as the signed-in user. For a user without all CiviCRM permissions and ACLs, SearchKit refuses to run an acl_bypass display except through an Afform that user may open, so name that Afform. SearchKit then returns the display's rows to anyone who may open the form, whatever their own ACLs. So the display is the boundary, and reviewing it is reviewing the tool.

Review it as SearchKit exposes it, not as the tool does. Anyone who may open the form can also run the display directly (civicrm/ajax/api4). There every selected field, every af-field on the embedding Afform, and every key of the display element's filters attribute is a filter that takes any APIv4 operator, and the last two need not be selected. The filters the tool declares narrow only the tool. So:

  • never select a field some callers must not see, even one the display does not show as a column. SearchKit also selects every field the display's settings refer to (column rewrites, links, icons and style rules, titles and empty values, editable columns, for example), so those count as selected;
  • never put an af-field or a filters key on such a field either: a filter is an oracle ({"LIKE": "a%"}) even when the field is never returned;
  • compute a per-row value in the select (IF(flag, field, NULL)) rather than hiding it with a column rule or a filter;
  • give the display no actions, links or editable columns: an acl_bypass display's inline edit writes without a permission check.

Not exceptions

These reads and writes skip the permission check without showing the user anything more:

  • the call-log writer saves its own fixed row (a write the user does not control, not a read);
  • ProfileStore reads the caller's own permission profile, keyed on the login and contact verified from their token (configuration, like reading a setting, and never part of a tool result; D39);
  • the DAO reads that only decide whether to refuse a write to an assignment, a group or a saved search (the assignment's save check, SmartGroupGuard), never returned;
  • the upgrader's own reads and writes, with no caller.