Nuxeo Server

Filters and Access Controls

Updated: December 5, 2017 Page Information Edit on GitHub

This page is scheduled for review and update. Check back soon for updated content!

Filters configuration allows to control activation of an action, to control its visibility depending on the user rights, for instance, or selected documents, etc.

Managing Filters to Control an Action Visibility

An action visibility can be controlled using filters. An action filter is a set of rules that will apply - or not - given an action and a context.

Filters can be registered using their own extension point, or registered implicitly when defining them inside of an action definition.

Example of a filter registration:

<filter id="view_content">
  <rule grant="true">
    <permission>ReadChildren</permission>
    <facet>Folderish</facet>
  </rule>
  <rule grant="false">
    <type>Root</type>
  </rule>
</filter>

Example of a filter registration inside an action registration:

<action id="newSection" link="#{documentActions.createDocument('Section')}"
    enabled="true" label="command.create.section"
    icon="/icons/action_add.gif">
  <category>SUBVIEW_UPPER_LIST</category>
  <filter id="newSection">
    <rule grant="true">
      <permission>AddChildren</permission>
      <type>SectionRoot</type>
    </rule>
  </filter>
</action>

A filter can accept any number of rules. It will grant access to an action if, among its rules, no denying rule (grant=false) is found and at least one granting rule (grant=true) is found. A general rule to remember is that if you would like to add a filter to an action that already has one or more filters, it has to hold constraining rules: a granting filter will be ignored if another filter is already too constraining.

If no granting rule (grant=true) is found, the filter will grant access if no denying rule is found. If no rule is set, the filter will grant access by default.

The default filter implementation uses filter rules with the following properties:

  • grant: a boolean indicating whether this is a granting rule or a denying rule.
  • permission: a permission like "Edit" that will be checked on the context for the given user. A rule can hold several permissions: it applies if user holds at least one of them.
  • facet: a facet like "Folderish" that can be set on the document type (org.nuxeo.ecm.core.schema.types.Type) to describe the document type general behavior. A rule can hold several facets: it applies if current document in context has at least one of them.
  • condition: an EL expression that can be evaluated against the context. The Seam context is made available for conditions evaluation. A rule can hold several conditions: it applies if at least one of the conditions is verified.
  • type: a document type to check against current document in context. A rule can hold several types: it applies if current document is one of them. The fake Server type is used to check the server context.
  • schema: a document schema to check against current document in context. A rule can hold several schemas: it applies if current document has one of them.
  • group: a group like "members" to check against current user in context. A rule can hold several groups: it applies if current user is in one of them.

Filters do not support merging, so if you define a filter with an id that is already used in another contribution, only the first contribution will be taken into account.

EL Expressions and Available Context Variables

When defining an action which visibility that depends on the current document, the currentDocument variable can be used inside a condition element.

The currentUser variable is also available, resolving to a NuxeoPrincipal instance, and can also be used inside a condition element.

All other variables available in the Seam context can also be used (Seam components for instance).

In some specific use cases, some additional variables are available, for instance when displaying actions on content view results. These actions are hidden when filters resolve to false, often the filter will check if there are selected documents. These filters can use the custom variable selectedDocuments, representing the list of entries that have been selected, or  contentView, representing the corresponding content view POJO.

Using Filters without Actions

Since 5.6, filters resolution can be done independently from actions. This makes it possible to benefit from filters configurability and override/merging features.

For instance, directoriesManagementAccess makes it possible to control access to a given directory:

<extension target="org.nuxeo.ecm.platform.actions.ActionService"
  point="filters">
  <filter id="directoriesManagementAccess">
    <rule grant="true">
      <condition>#{currentUser.administrator}</condition>
      <condition>#{currentUser.isMemberOf('powerusers')}</condition>
    </rule>
  </filter>
</extension>

This can be looked up in the code, by calling the action service, and evaluating the filter given an evaluation context:

ActionManager actionManager = Framework.getLocalService(ActionManager.class);
return actionManager.checkFilter("directoriesManagementAccess", createActionContext(ctx));

This also can be looked up in XHTML templates, calling Seam component webActions and using its default evaluation context:

<c:if test="#{webActions.checkFilter('directoriesManagementAccess')}">
  [...]
</c:if>

 

Debugging Filters

It can be useful to activate server logs to help debugging filters resolution. Logs are verbose, here is the configuration to setup to see these logs on the sever lib/log4j.xml configuration file:

  <category name="org.nuxeo.ecm.platform.actions.ActionService">
    <priority value="TRACE" />
  </category>

7 days ago Manon Lumeau add tags for doc days
14 days ago GitHub update label
a month ago manonlumeau Added content-review-lts2017 label
2 months ago manonlumeau NXDOC-1346-FT review screenshot
a year ago Manon Lumeau 18 | emove deleted pag
a year ago Anahide Tchertchian 17 | add tip to help debugging filters
2 years ago Manon Lumeau 16
2 years ago Vincent Dutat 14
2 years ago Vincent Dutat 15
2 years ago Manon Lumeau 13 | replace "Write" by "Edit"
2 years ago Solen Guitter 12 | Update related pages
2 years ago Anahide Tchertchian 11
3 years ago Manon Lumeau 10
3 years ago Vincent Dutat 9
3 years ago Anahide Tchertchian 8 | NXDOC-222: mention currentUser availability in action context
4 years ago Solen Guitter 7
4 years ago Solen Guitter 6
4 years ago Anahide Tchertchian 5 | add more info about context + filters without actions
4 years ago Anahide Tchertchian 4
4 years ago Anahide Tchertchian 3 | remove deprecated warning for 5.8
4 years ago Anahide Tchertchian 2 | move content from parent page + add wip warning
4 years ago Anahide Tchertchian 1
History: Created by Anahide Tchertchian