Upgrade Security Configuration

Depending on your exact project security customizations, you need to take more or less actions. However even if you did not make any customizations, still some actions are required. See the beginning of this document. If you have custom Security Domains, you will also need to account for rewriting these to be compliant with the new model. Make sure to first read Security Configuration Overhaul. 

Headsup

Upgrading the Security Configuration is by far the most complex and delicate part of the upgrade to version 14.0.0. We recommend the strategy depicted below, certainly in case you have specific custom security configurations and domains setup in your yaml bootstrap configuration. Because we really needed to make some fundamental changes to make the setup much easier and future proof hereafter, we had to make some hard decisions, like for example the inability to provide a generic tool rewriting custom security domains: that turned out to be impossible because the security domain setup coming from the product had to change so much.
What really will help going through the following steps is to make sure that you know the reasons and intentions of for your custom security domains, if you have them. Try to capture these on a functional level in some document, let's call it Security-Tasks.doc. For example Members of Group X are only allowed to be Author on folders below Y, or Only members of group X are allowed to read and edit documents marked with property Y with value Z. When you have this, then, combined with all the explanations at Authorization Model Concepts, and most specifically the rewritten walkthroughs at Authentication and Authorisation Walkthroughs for the CMS (platform) webapp and Authentication and Authorisation Walkthroughs for the delivery tier (HST) webapp, you will be able to redefine these rules (if even needed!) with the steps below. We also enormously improved the View Permissions of a User in the Console to help developers and administrators to better understand, verify and configure the effective security domains.

Prerequisite

If you have any production security domains changes not present in the project bootstrap yaml files, make sure these are first merged and reintegrated in the project bootstrap while your project is still on version 13.4.x, see step 1 in the General Introduction to Bloomreach Experience Manager Upgrades. 

Remove Delivery Tier Bootstrap Users / Groups

Before Bloomreach Experience Manager 14, the archetype created a local project containing the following files at 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 made modifications to this files (look at version history or compare them with a plain archetype 13.4 project), sort out why these changes are there and write them to your document Security-Tasks.doc, to account for later. Next step is, simply delete all the files above. They are not needed any more, since all the users in there are sytem users needed by the delivery tier, and from now on, already provided by the delivery tier. The delivery tier itself now bootstraps these users like liveuser, previewuser, etc. And delivery tier groups like liveusers, previewusers etc won't be bootstrapped any more since the are redundant and no longer needed.

After that, make sure to remove all the usages of sitewriters, liveusers and previewusers. An archetype project from before version 14 had these configured in repository-data/application/src/main/resources/hcm-config/configuration/config.yaml. Remove from config.yaml this part:

/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]

Note that if you do not have the above yaml files in your project, possibly the yaml files have been reshuffled or merged in your project, or because of upgrades from older versions. In that case, find the parts in the files above (which you can find by an archetype created project in version 13.4) in your project yaml bootstrap and then remove those parts.

Disable all custom Security Domains

In your project yaml files, search for all occurences of (the string) /hippo:domains, and comment out the hippo:domains part(s) (prefix the lines with #) , or possibly you can rename the whole file xyz.yaml to xyz.bak. These are your custom security domains changes which needs to be reconciled later.

Assert your project starts locally again

Before working on the next steps, you have to make sure your project starts again correctly. This might require that you also account for Upgrading the HST Code and Upgrade to Navapp, etc. for example in case you also need to see custom perspectives, if you have those. If you get bootstrap errors, first solve those. If you have bootstrap warnings, it is highly recommended to first fix those before continuing with the next steps.

Include and adjust all production (only) groups in the project bootstrap configuration 

Now that you have your project running locally again, you can best reconcile production groups (without the members!) which are not (yet) present in local bootstrap. If you do not want this, you can skip this step but it does imply you have to make post-upgrade deployment changes at runtime to production groups which is described in the next section (Adjust Custom Groups). You can easily achieve reconciling the production groups to your project bootstrap by making sure you run your project (locally) with auto-export enabled. From production, copy a yaml export of a production group (aka a group that is not bootstrapped by Bloomreach Experience Manager 14 and is not present in your project bootstrap yet) to you clipboard, import the clipboard yaml to your local running project below /hippo:configuration/hippo:groups and then remove the property hipposys:members : the members (users) are really production only data (note that instead of removing the property hipposys:members you can also remove all the values). 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

in case you did completely remove the hipposys:members property. The only thing you really have to take care of is that it does not contain

hipposys:members:[]

The above would make the hipposys:members property configuration, implying that on a new deployment, it will override and replace the existing hipposys:members property which you most definitely don't want to! 

Adjust Custom Groups

In version 14, on a group you typically configure what the userroles of the members in the group are (note you can also specify the userroles on a specific user but this can typically only be done in production since normally you don't, nor should, define users through project yaml bootstrap). The next step is to figure out what the custom groups should be able to do and add those userroles. Either directly in production as a post-ugrade task (using the Setup > System > Groups application), or upfront through the project yaml bootstrap, as explained below.

If for example a specific group needs to be able to 

1. log in into the CMS
2. see the Dashboard
3. see the Content Perspective 
4. see reports Perspective

then you modify the mygroup example above into:

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 the members of the group also need for example to be able to view channels in the Experience Manager, you have to add 

xm.channel.user, xm.channel.viewer

See Userroles for information per userrole and what it is for.

If however your custom groups are setup and used for the same purpose as the standard provided groups, e.g. admin, author, editor, webmaster, for example in case of LDAP integration, then maybe you only need to configure the  one matching xm.default-user.* userrole, e.g. xm.default-user.author. Again, see Userroles for the precise definition per userrole. 

Rewrite Custom Security Domains

At the above step Disable All Custom Security Domains you have temporarily disabled all custom security configuration and you have described the customization reasons in  Security-Tasks.doc,. We are now in the position to start enabling them one by one again. Custom Security Domains which were created before version 14 fall into three categories for upgrading

1. Obsolete with version 14
2. Moved in version 14
3. Reconfiguration / rethinking needed in version 14

Category Obsolete

Typically these are security domains giving read access to custom JCR Nodes below /hippo:configuration for for examples editors and authors. In general, these custom security domains are not needed any more. Another category of now redundant custom domains are domains that were used to give explicit read access to a set of ancestor nodes below which a user had to have some privileges. For example when you wanted to have a group of users to have privilege hippo:author on a deeper nested folder, eg /content/document/myproject/news, then this group of users also required explicit read access to all parent (ancestor) nodes. In version 14, when a domain is configured with jcr:path = /content/document/myproject/news and equals = true, then the ancestors of news will automatically get implicit read access, and thus domains that were added to give read access to ancestors can now be removed. Typically domains to give explicit read access to a specific node make use of jcr:uuid facet, for example

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

Another category of obsolete domains are domains that were used to show/hide certain perspectives or features to CMS users. These domain facet rules were typically named something like exclude-<something> or hide-<something>. These now are all obsolete and much easier done using Userroles.

Moved

If you rely on bootstrapping some customization to a domain, it might be that the domain has been completely removed or moved (renamed). The most important domain which you might rely on that has been moved is /hippodocuments. It used to be this:

/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

This domain has been replaced with /content, which look as follows (skipped the empty users and groups properties:

/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 for example in version 13 you excluded some document path (say administration) for the default authors / editors using:

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

you now have to bootstrap that into /hippo:configuration/hippo:domains/content, see Deny Access to a Folder for a worked out example.

Reconfiguration / rethinking

A lot of security domains that were required in version 13 are not needed any more, or need to be done completely different. Unfortunately since version 14 now has a radically different default setup, it is not possible to automatically reconcile all the required changes for every project. The good news is that a lot of configuration, which was really hard in versions before 14, now is much easier to accomplish. If you look at your inventory of Security-Tasks.doc of items that are not yet resolved in the above step, or turned out to be obsolete, they you must figure out what you still need to reconcile. At Authentication and Authorisation Walkthroughs for the CMS (platform) webapp and Authentication and Authorisation Walkthroughs for the delivery tier (HST) webapp we have rewritten and added a set of common scenarios which should help you transforming the custom security domains to the new setup.

Possibly Required Code and Usage Changes

From Security Configuration Overhaul you can read that the write access on content for editors now has been limited to only the draft document variant they are holder of (aka, when editing a document the variant being edited). Before v14 editors could also write to other document variants (live and preview), and to folders. If you have code relying on this, you either need to give the editor more write access (disadviced) or change the code to delegate the changes to be made by an impersonated workflow session.

The default read access for the sitewriter has also been restrained by default. Accounting for this in code if needed is described in Upgrade HST Code.

Likewise, before v14 default read access was granted to specific or more generic node types, like nt:unstructured, or to specific services configurations like under /hippo:configuration/hippo:modules. In v14 the default read access in general has been hardened and largely removed where not technically needed or desired.

If either through code, or configuration, specific custom features, like importers or other services relied on such default read access, and were access this with a 'regular' user, chances are that may now need to corrected to use a proper and dedicated 'system' user (and then preferrably a JVM Enabled User).

Therefore, make sure to verify and test all such custom 'service' type of features are all working correctly with your updated security configuration.

Providing feedback and tips