Limit Access to Documents for Site Visitors

Important: YAML Configuration in Walkthroughs

When following the walkthroughs, you will often import YAML configuration into a locally running repository using the Console with auto-export enabled. If you copy a YAML snippet directly into your project without using auto-export, uncomment the following lines if they are present:

#.meta:category: system
#.meta:add-new-system-values: true

Auto-export automatically adds this meta information for certain properties. However, the Console's YAML import does not support .meta lines. You have two options:

Import the YAML snippet as-is into the Console with auto-export enabled.
Copy the YAML snippet into your project and uncomment the .meta lines.

Overview

This page describes how to restrict access to documents for specific user groups by configuring authorization at the document level.

Use Case

You may need to ensure that only certain users (for example, staff or customers) can access specific documents on your site. Bloomreach Content supports authorization at the mount, sitemap item, and document levels using security domains.

This example demonstrates how to configure document-level authorization.

Example Implementation

This example uses a standard project created from the Maven archetype with the Blog feature added.

Requirements

Users are either customers or staff members.
Some Blog documents are restricted to visitors with permission to read staff or customer labeled blogs.
Blog documents labeled customer are accessible to both customers and staff.
Blog documents labeled staff are accessible only to staff.

Implementation Approach

Use the Selections feature to define access levels and make them selectable in Blog documents.
Create roles and groups for customers and staff.
Configure separate security domains for documents with customer access, staff access, and no access level.
Configure the delivery tier to use the logged-in user's session for authorization at the document level. For production or high-traffic sites, use a specialized session pool as described in Custom Session Pools – A Case Study.

Project Preparation

Create a project using the Bloomreach Content Maven archetype.
Build and run the project.
In Essentials, add the Blog feature.
Rebuild and restart the project.
In the Console, select /hst:myproject/hst:configurations/hst:default/hst:sitemap/login and set the hst:scheme property to http. This change configures the login page to use HTTP in your local environment. Do not use HTTP in production.

Add an Access Level Field to the Blog Document Type

Define access levels using the Selections feature:

In the CMS, create a subfolder named 'value lists' under 'myproject'.
Inside 'value lists', create a new Value List document called 'access levels'.
Add the following entries:

Key Label
customer Customer
staff Staff
Save the value list.
In Essentials, go to Tools > Selections.
On the Document Types tab, add a selection field to the Blog document type:
- Select 'blogtype'.
- Name the field 'access level'.
- Set selection type to 'multiple'.
- Set presentation to 'checkboxes'.
- Choose the 'access levels' value list.
- Click 'Add new selection field'.

Key	Label
customer	Customer
staff	Staff

Restrict Read Access for Unauthorized Visitors

To prevent anonymous visitors from reading Blog documents labeled with staff or customer access levels, update the default live-documents security domain.

At /hippo:configuration/hippo:domains/live-documents/hippo-document, add:

/exclude-staff-docs:
  jcr:primaryType: hipposys:facetrule
  hipposys:equals: false
  hipposys:facet: myproject:accesslevel
  hipposys:filter: true
  hipposys:type: String
  hipposys:value: staff

/exclude-customer-docs:
  jcr:primaryType: hipposys:facetrule
  hipposys:equals: false
  hipposys:facet: myproject:accesslevel
  hipposys:filter: true
  hipposys:type: String
  hipposys:value: customer

After this change, the default HST liveuser cannot read live documents where:

myproject:accesslevel = staff

myproject:accesslevel = customer

Note: The property hipposys:filter: true ensures that the constraint applies only if the myproject:accesslevel property is present.

Create Security Domains for Staff and Customer Visitors

To allow authenticated users in the customers or staff groups to read restricted documents, create separate security domains.

Customer Domain:

Copy /hippo:configuration/hippo:domains/live-documents to /hippo:configuration/hippo:domains/live-documents-customer.
Remove the /exclude-customer-docs node.
Replace the readonly node with:

/readonly:
  jcr:primaryType: hipposys:authrole
  hipposys:role: readonly
  hipposys:groups:
    #.meta:category: system
    #.meta:add-new-system-values: true
    type: string
    value: [customers]

Staff Domain:

Copy /hippo:configuration/hippo:domains/live-documents-customer to /hippo:configuration/hippo:domains/live-documents-staff.
Remove the /exclude-staff-docs node.
Replace the readonly node with:

/readonly:
  jcr:primaryType: hipposys:authrole
  hipposys:role: readonly
  hipposys:groups:
    #.meta:category: system
    #.meta:add-new-system-values: true
    type: string
    value: [staff]

With this configuration:

Users in the customers group can read documents where myproject:accesslevel = customer.
Users in the staff group can read all blog documents.
The default HST liveuser cannot read documents with myproject:accesslevel = customer or staff.

Create Customer and Staff Groups

Under /hippo:configuration/hippo:groups, create two groups:

/customers:
  jcr:primaryType: hipposys:group
  hipposys:members:
    .meta:category: system
    .meta:add-new-system-values: true
    type: string
    value: []
  hipposys:securityprovider: internal
  hipposys:userroles: [xm.webfiles.reader]

/staff:
  jcr:primaryType: hipposys:group
  hipposys:members:
    .meta:category: system
    .meta:add-new-system-values: true
    type: string
    value: []
  hipposys:securityprovider: internal
  hipposys:userroles: [xm.webfiles.reader]

Create new users and assign them to either the customers or staff group. Do not assign existing CMS users to these groups, as CMS users have broader read access, including preview versions. If you need CMS users to log in to the website, use specialized session pools (such as staff-liveuser or customer-liveuser). For details, see Custom Session Pools – A Case Study.

Set Access Levels for Individual Documents

Assign access levels to individual Simple Content documents:

In the CMS, create Simple Content documents in the myproject/blogs folder.
Set the access level to customer, staff, or both.
Save and publish the documents.

Set up login using JAAS as described in Delivery Tier Authentication Configuration.

Note: The following configuration uses the JCR session of the authenticated user (hst:subjectbasedsession: true). For high-traffic sites or when many users share access, use custom session pools for better performance. See Custom Session Pools – A Case Study.

Configure Authorization Using the Logged-In User's Session

To authorize using the logged-in user's session:

In the Console, select /hst:myproject/hst:hosts/dev-localhost/localhost/hst:root.
Set these properties to true:

/hst:myproject/hst:hosts/dev-localhost/localhost/hst:root:
  hst:sessionstateful: true
  hst:subjectbasedsession: true

This configuration instructs the delivery tier to use the logged-in user's session for authorization instead of the standard liveuser. This approach has a performance impact and does not allow CMS users to log in as site visitors, since CMS users have broader access (including preview and live variants). For most scenarios, maintain dedicated users for site login. For advanced use cases, implement custom session pools as described in the referenced case study.