Upgrade Security Configuration

Upgrading your security configuration for brXM 14 requires specific actions, even if you have not customized your security setup. Review the information at the start of this page before proceeding. If your project includes custom Security Domains, you must update them to comply with the new security model. Before starting, read Security Configuration Overhaul for an overview of the changes.

Overview

Upgrading the security configuration is the most complex part of migrating to version 14.0.0. If your project includes custom security configurations or domains in your YAML bootstrap files, follow the strategy outlined below. The security model has changed significantly, and it is not possible to provide a generic tool to rewrite custom security domains due to the extent of these changes.

Before you begin, document the purpose of your custom security domains at a functional level. For example, specify requirements such as “Members of Group X can only be Authors on folders below Y” or “Only members of group X can read and edit documents with property Y set to value Z.” Record these requirements in a document (for example, Security-Tasks.doc). Use Authorization Model Concepts, Authentication and Authorisation Walkthroughs for the CMS (platform) webapp, and Authentication and Authorisation Walkthroughs for the delivery tier (HST) webapp to help redefine these rules as needed. The View Permissions of a User in the Console tool has also been improved to help you verify and configure effective security domains.

Prerequisite

If you have made changes to security domains in production that are not present in your project’s bootstrap YAML files, merge and reintegrate these changes into the project bootstrap while your project is still on version 13.4.x. See step 1 in the General Introduction to Bloomreach Content Upgrades.

Remove Delivery Tier Bootstrap Users and Groups

Prior to version 14, the archetype created the following files in repository-data/application/src/main/resources/hcm-config/security:

  1. configuser-read-everywhere.yaml
  2. group-liveusers.yaml
  3. group-previewusers.yaml
  4. group-sitewriters.yaml
  5. user-configuser.yaml
  6. user-liveuser.yaml
  7. user-previewuser.yaml
  8. user-sitewriter.yaml
  9. webfiles.yaml

If you have modified any of these files, review the changes and document their purpose in Security-Tasks.doc for later reference. Then, delete all the files listed above. These files are no longer required—system users such as liveuser and previewuser are now provided by the delivery tier itself. Delivery tier groups like liveusers and previewusers are now redundant and should not be bootstrapped.

Next, remove all references to sitewriters, liveusers, and previewusers from your configuration. In projects created before version 14, these groups are typically configured in repository-data/application/src/main/resources/hcm-config/configuration/config.yaml. Remove the following section from config.yaml:

/hippo:configuration/hippo:domains/hippofolders/readonly:
  hipposys:groups:
    operation: add
    type: string
    value: [sitewriters]
/hippo:configuration/hippo:domains/preview-documents/readonly:
  hipposys:groups:
    operation: add
    type: string
    value: [previewusers]
/hippo:configuration/hippo:domains/live-documents/readonly:
  hipposys:groups:
    operation: add
    type: string
    value: [liveusers]

If these YAML files are not present, they may have been merged or reorganized in your project. Compare your project files with a plain archetype 13.4 project to locate and remove the relevant configuration.

Disable All Custom Security Domains

In your project YAML files, search for all occurrences of /hippo:domains. Comment out the hippo:domains sections (prefix lines with #), or rename the entire file from xyz.yaml to xyz.bak. These represent your custom security domain changes, which you will reconcile later.

Verify Local Project Startup

Before proceeding, ensure that your project starts successfully in your local environment. You may also need to address Upgrading the HST Code and Upgrade to Navapp, especially if you use custom perspectives. Resolve any bootstrap errors before continuing. Address bootstrap warnings as well before moving to the next steps.

Add and Adjust Production-Only Groups in Bootstrap Configuration

Once your project runs locally, reconcile any production groups (excluding group members) that are not present in your local bootstrap configuration. If you prefer, you can skip this step and make post-upgrade changes at runtime, as described in the next section (Adjust Custom Groups).

To reconcile production groups:

  • Run your project locally with auto-export enabled.
  • Export a YAML definition of a production group (i.e., a group not bootstrapped by brXM 14 and not present in your project bootstrap).
  • Import the YAML to your local running project under /hippo:configuration/hippo:groups.
  • Remove the hipposys:members property (or remove all its values). Group membership is production-only data.

After writing the changes to the repository, auto-export will export the group to your local project YAML bootstrap configuration, for example:

definitions:
  config:
    /hippo:configuration/hippo:groups/mygroup:
      jcr:primaryType: hipposys:group
      hipposys:system: true
      hipposys:members:
        .meta:category: system
        .meta:add-new-system-values: true
        type: string
        value: []
      hipposys:securityprovider: internal

or

definitions:
  config:
    /hippo:configuration/hippo:groups/mygroup:
      jcr:primaryType: hipposys:group
      hipposys:system: true
      hipposys:securityprovider: internal

if you removed the hipposys:members property entirely.

Important:
Do not include hipposys:members: [] in your project bootstrap. This would make hipposys:members a configuration property, which would override and replace existing group members on deployment. See Avoid Potentially Destructive Configuration.

If you use an external security provider (such as LDAP) and synchronize users and groups during local development, these actions are handled automatically with auto-export enabled. In this case, you may need to add externally managed user/group properties (like hipposys:members) as exclusions in the auto-export configuration.

Adjust Custom Groups

In version 14, you typically assign userroles to group members. You can also assign userroles to individual users, but this is usually done only in production, as users are not typically defined through project YAML bootstrap.

To assign userroles to a group, update the group definition. For example, if a group should be able to:

  1. Log in to the CMS
  2. Access the Dashboard
  3. Access the Content Perspective
  4. Access the Reports Perspective

update the group configuration as follows:

definitions:
  config:
    /hippo:configuration/hippo:groups/mygroup:
      jcr:primaryType: hipposys:group
      hipposys:system: true
      hipposys:members:
        .meta:category: system
        .meta:add-new-system-values: true
        type: string
        value: []
      hipposys:securityprovider: internal
      hipposys:userroles:
        .meta:category: system
        .meta:add-new-system-values: true
        type: string
        value: [xm.cms.user, xm.content.user, xm.report.user, xm.dashboard.user]

If group members also need to view channels in Experience Manager, add:

xm.channel.user, xm.channel.viewer

Refer to Userroles for details about each userrole.

If your custom groups serve the same purpose as standard groups (such as admin, author, editor, webmaster), for example with LDAP integration, you may only need to configure the corresponding xm.default-user.* userrole (e.g., xm.default-user.author). See Userroles for definitions.

Rewrite Custom Security Domains

After disabling all custom security domains and documenting their purpose in Security-Tasks.doc, you can begin re-enabling them as needed. Custom Security Domains created before version 14 fall into three categories:

  1. Obsolete in version 14
  2. Moved in version 14
  3. Require reconfiguration or redesign in version 14

Obsolete Domains

Domains that granted read access to custom JCR nodes under /hippo:configuration for editors and authors are generally no longer needed. Domains that granted explicit read access to ancestor nodes (e.g., to allow a group to have hippo:author privilege on a nested folder) are also obsolete. In version 14, if a domain is configured with jcr:path = /content/document/myproject/news and equals = true, ancestor nodes automatically receive implicit read access. Domains that used the jcr:uuid facet for this purpose can be removed, for example:

jcr:primaryType: hipposys:facetrule
hipposys:equals: true
hipposys:facet: jcr:uuid
hipposys:filter: false
hipposys:type: Reference
hipposys:value: /content

Domains used to show or hide CMS perspectives or features (often named exclude-<something> or hide-<something>) are now obsolete. Use Userroles instead.

Moved Domains

Some domains have been removed or renamed. For example, the /hippodocuments domain has been replaced with /content. The previous configuration:

/hippodocuments:
  jcr:primaryType: hipposys:domain
  /hippo-document:
    jcr:primaryType: hipposys:domainrule
    /nodetype-hippo-document:
      jcr:primaryType: hipposys:facetrule
      hipposys:equals: true
      hipposys:facet: nodetype
      hipposys:filter: false
      hipposys:type: Name
      hipposys:value: hippo:document
    /hide-prototypes:
      jcr:primaryType: hipposys:facetrule
      hipposys:equals: false
      hipposys:facet: nodename
      hipposys:filter: false
      hipposys:type: Name
      hipposys:value: hipposysedit:prototype
  /editor:
    jcr:primaryType: hipposys:authrole
    hipposys:groups: [admin, editor]
    hipposys:role: editor
  /author:
    jcr:primaryType: hipposys:authrole
    hipposys:groups: [author]
    hipposys:role: author

is now replaced by /content:

/content:
  jcr:primaryType: hipposys:domain
  /content-domain:
    jcr:primaryType: hipposys:domainrule
    /content-and-descendants:
      jcr:primaryType: hipposys:facetrule
      hipposys:equals: true
      hipposys:facet: jcr:path
      hipposys:type: Reference
      hipposys:value: /content
  /author:
    jcr:primaryType: hipposys:authrole
    hipposys:role: author
    hipposys:userrole: xm.content.author
  /editor:
    jcr:primaryType: hipposys:authrole
    hipposys:role: editor
    hipposys:userrole: xm.content.editor
  /admin:
    jcr:primaryType: hipposys:authrole
    hipposys:role: admin
    hipposys:userrole: xm.content.admin
  /readonly:
    jcr:primaryType: hipposys:authrole
    hipposys:role: readonly
    hipposys:userrole: xm.content.viewer

If you previously excluded a document path (such as administration) for default authors or editors using:

/exclude-administration:
  jcr:primaryType: hipposys:facetrule
  hipposys:equals: false
  hipposys:facet: jcr:path
  hipposys:type: Reference
  hipposys:value: /content/documents/administration

you must now bootstrap this configuration into /hippo:configuration/hippo:domains/content. See Deny Access to a Folder for an example.

Domains Requiring Reconfiguration

Many security domains required in version 13 are no longer necessary or must be implemented differently in version 14. The default setup has changed significantly, and there is no automated way to reconcile all required changes. However, many configurations are now easier to implement. Review your Security-Tasks.doc for unresolved items or items that are now obsolete. Use the updated Authentication and Authorisation Walkthroughs for the CMS (platform) webapp and Authentication and Authorisation Walkthroughs for the delivery tier (HST) webapp for guidance on transforming custom security domains to the new model.

Code and Usage Changes

As described in Security Configuration Overhaul, editors’ write access to content is now restricted to the draft document variant they are editing. Previously, editors could write to other document variants (such as live and preview) and to folders. If your code depends on this behavior, either grant editors additional write access (not recommended) or update your code to perform changes using an impersonated workflow session.

The default read access for the sitewriter has also been restricted. If your code relies on broader read access, see Upgrade HST Code for guidance.

In earlier versions, default read access was granted to certain node types (such as nt:unstructured) or to service configurations under /hippo:configuration/hippo:modules. In version 14, default read access has been hardened and removed where not technically required.

If your code or configuration relies on this default access (for example, for importers or custom services using a regular user), you may need to update these features to use a dedicated system user (preferably a JVM Enabled User).

Test and verify all custom service features after updating your security configuration to ensure they function correctly.

Feedback and Tips

Note:
These upgrade steps address common scenarios but may not cover all use cases.
If you encounter a complex or common scenario and can share your solution, please provide feedback so we can improve these instructions.

Share Feedback
Page: /about/upgrade-guides/archived-upgrades-pre-v15/v13-v14/upgrade-security-configuration
Section: About
Category *