Security Domains - Bloomreach Experience - Open Source CMS
06-12-2019

Security Domains

A security domain defines a set of repository nodes for which specific access privileges can be configured for one or more users, groups or users having a specific userrole.

Domains Configuration

Domain Folder

Common and general security domains are stored in the repository as children of the security domain folder parent node at /hippo:configuration/hippo:domains of type hipposys:domainfolder.

node type definition

[hipposys:domainfolder] > nt:base
+ * (hipposys:domain) = hipposys:domain

Federated Domain Folders

Security domains can also be defined as children of specific federated security domain folder nodes of node type hipposys:federateddomainfolder.

Federated domain folders simplify and restrict security domain facet rules to be only applicable and relative to the parent path of the federated domain folder itself. This means that security domains within a federated security domain can only select nodes within that folder its parent path, and jcr:path or jcr:uuid facet rules must use a path value relative to that parent path.

For example take the Poll Plugin. This is an optional plugin for supporting polls. It stores poll results in a dedicated part of the repository below /polldata. When adding the poll plugin, below/polldata also a security domain is stored at /polldata/poll:domains defining who has which authorization on /polldata and its descendants.

node type definition

[hipposys:federateddomainfolder] > hipposys:domainfolder

Security Domain

Security domain nodes are of node type hipposys:domain and must have at least one domain rule child node.

node type definition

[hipposys:domain] > nt:base
+ * (hipposys:domainrule) = hipposys:domainrule
+ * (hipposys:authrole) = hipposys:authrole
- hipposys:description (string)

Domain Rule

Domain rule node are of type hipposys:domainrule and is a container for one or more facet rules child nodes.

node type definition

[hipposys:domainrule] > nt:base
+ * (hipposys:facetrule) = hipposys:facetrule
- hipposys:description (string)

Facet Rule

Facet rule nodes are of type hipposys:facetrule and are used for selecting a set of nodes in the repository.

A facet rule is made up of a facet name and a value. The facet name, stored in the property hipposys:facet is the name of the property (facet) of the node (for example a document) to do the matching on. The value of the facet to match on is stored in the hipposys:value property.

Negating

A facet rule can be negated by setting the hipposys:equals property to false. This means that the rule matches all nodes that do have the facet but not that value.

Filtering

A facet rule in filtering mode is only applied to nodes that have the specific facet. All nodes that don't have the specific facet will match the rule and all nodes that have the facet and the specified value will match the rule. The facet rule can be set in filtering mode by setting the property hipposys:filter to true.

Rule Types

A facet rule must be one of the following types:

  • String : normal string matching

  • Name : a jcr Name used for node name and mixin types

  • Reference : a reference type looks up the uuid of a node specified with a path in the value. The matching is then done as a String type on the uuid of the node.

Special facet names

  • jcr:primaryType : match the exact node type

  • jcr:mixinTypes : match any of the mixin types

  • nodetype : match the exact node type of any subtypes

  • nodename : match the node name

Special facet values

  • * : match any value

  • __user__ : match the name of the current user

  • __group__: match any group the current user is a member of

  • __role__: match the current user's role (for the domain)

node type definition

[hipposys:facetrule] > nt:base
- hipposys:facet (string) mandatory
- hipposys:value (string) mandatory
- hipposys:type (string) = 'String' mandatory < 'String', 'Name', 'Reference'
- hipposys:equals (boolean) = 'true' mandatory autocreated
- hipposys:filter (boolean)
- hipposys:description (string)

Name

Type

Required

Description

node name

String

yes

hipposys:facetrule

hipposys:facet

String

yes

The name of the facet to match. There are two special values possible:

  1. nodetype : matches all nodes of the type specified in hipposys:value.
  2. jcr:uuid: matches the node at the absolute path specified in hipposys:value.
    Note that hipposys:type must be Reference.
  3. jcr:path: matches all nodes that are either at, or a descendant of the absolute path specified in by hipposys:value.
    Note that hipposys:type must be Reference.

The use of the facet hippo:paths is no longer recommended because it only matches nodes that have a hippo:paths property, potentially leaving nodes unsecured. Use jcr:path instead.

hipposys:value

String

yes

The value of the facet to match. Four special values can be used:

  • * : match everything
  • __role__: match the current user's role (for the domain)
  • __user__: match the current username
  • __group__: match any of the current user's groups

Furthermore, for matched properties of type Boolean, Long or Double the String representation of the native value can be used, e.g. "10.1" for a Double or "true" for a Boolean.

hipposys:type

String

yes

The property type of the facet. Must be either String, Name or Reference.

hipposys:equals

Boolean

yes

Whether the value must match or must not match. If set to false the hippo:facetrule is only effective if the facet actually exists.

hipposys:filter

Boolean

no

Whether the facet must exist to create a match. If set to true the hippo:facetrule is only effective if the facet actually exists.

The effect and usage of the hipposys:filter property is tricky and only needed for one specific condition, when hipposys:equals=true but the facet doesn't exist, as shown in the table below. For that condition using hipposys:filter=true will include the node, otherwise it will be excluded.

  hipposys:filter=false (default) hipposys:filter=true
facet exists facet doesn't exist facet exists facet doesn't exist
hipposys:equals=true match: include
!match: exclude
exclude match: include
!match: exclude
include
hipposys:equals=false match: exclude
match: include
include match: exclude
!match: include
include

Authrole

Finally, security domains can have one or more authrole child nodes of type hipposys:authrole to grant a specific repository role (and thereby that role its privileges) to users, groups or users having a specific userrole, for accessing the selected nodes of the domain.

hipposys:authrole node type definition

[hipposys:authrole] > nt:base
- hipposys:users (string) multiple
- hipposys:groups (string) multiple
- hipposys:userrole (string)
- hipposys:role (string) mandatory
- hipposys:description (string)

Name

Type

Required

Description

node name

String

yes

The name of the authrole

hipposys:role

String

yes

The repository role to grant to the configured users, groups or users having the userrole, for the selected nodes in the domain.

hipposys:users

String

no

The users that are granted the repository role in the domain.

hipposys:groups

String

no

The groups that are granted the repository role in the domain.

hipposys:userrole String no The userrole users must have to be granted the repository role in the domain

Implicit Read Access to Ancestors

If a domain rule contains a jcr:path facet rule which is a hierarchical whitelist constraint, aka it has

  1. hipposyst:facet = jcr:path
  2. hipposys:equals = true
  3. hipposys:value = /some/path/subpath

then all the ancestors of /some/path/subpath do get automatic (implicit) read access (jcr:read) for a user if and only if

  1. The rest of the facet rules in the domain rule do not exclude /some/path/subpath from matching
  2. The domain containing all the domain rules at least has jcr:read privilege for the user via some authrole

This implicit read access to ancestors has been implemented in version 14.0.0 and was not supported previously. It makes it much easier to configure certain privileges for a user at a deeper located node in the repository.

jcr:path and jcr:uuid facet rules are very similar in that they both use an absolute path value to configure, but jcr:uuid facet rules do not apply to decendants of the path. And implicit read access to ancestors is only available and provided for jcr:path facet rules, not jcr:uuid

Custom Security Domains

When working on custom security domains, it is very handy to view the permissions of a user on certain nodes via the Console. This feature is available since 14.0.0 and is documented at View Permissions of a User in the Console. Furthermore it is of paramount importance to realize that

Security Domains are configuration (apart from some properties which are system)

This is very important to realize. See Configuration vs Content (vs System) for the difference between the categories. And because security domains are configuration, a developer has to make sure changes to the security domain configuration end up in local bootstrap. If not, on new deployments the custom domains, domain rules or auth roles can and will be deleted

If a CMS user has userrole xm.security.application-admin, that user can runtime modify auth roles within security domains, for example through the CMS UI (Setup > System > Permissions). Such changes typically should (also) be made as a developer with auto-export enabled to ensure they become part of the bootstrap configuration. When changes to security domains are (directly) needed and made in production, a developer has to make sure the production changes get reconciled into bootstrap configuration, for example by using the Configuration Verifier, before a next deployment which otherwise may destroy those changes.

Examples

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?