Delivery Tier Authorization Configuration

Introduction

Goal

Configure authorization in Bloomreach Experience Manager's delivery tier.

Note

Background

Bloomreach Experience Manager's delivery tier supports authorization at mount and sitemap item levels out-of-the-box. This page describes how to configure authorization at mounts and sitemap item levels.

This authorization ties in into the configuration options for the RepositoryAuthenticationProvider, to see the authorization described here  and RepositoryAuthenticationProvider configuration come together, see the examples at Authentication and Authorisation Walkthroughs.

Authorization Configuration

Web Application Level Authorization

You can secure a Mount and/or Sitemap item (URL) by setting the hst:authenticated boolean property to true : this means a user has to be authenticated before allowed access to the Mount and/or Sitemap item. A URL is only accessible if and only if the the Sitemap Item for the URL is allowed access for the visitor, as well as every ancestor Sitemap Item and the Mount. Every ancestor Sitemap Item and Mount are checked independantly for access. 

Besides setting a Mount or Sitemap Item to require authentication, it is also possible to specify the authorized roles and which specific users are allowed. This is done in the multi-valued string properties hst:roles or hst:users on the Mount or Sitemap item.

For example, if you set the following properties on a mount:

hst:authenticated: true
hst:roles: [staff]

then, the Mount will be accessible only to authenticated users in role staff. If an unauthenticated user accesses this resource, the response is an HTTP Not Authenticated (401) error and the user is redirected to the login form. If the user is authenticated but is not in role staff, then the response will be an HTTP Forbidden error (403).

Instead of protecting the entire mount, it is also possible to protect single or multiple sitemap items, for example by setting 

+ hst:sitemap
  + blog
     - hst:authenticated: true
     - hst:roles: [staff]
     + _any_.html
     + _any_

Then only authenticated users in role staff can access the /blog and descendant URLs. 

Note that even when you have configured the hst:mount to be authenticated, you do need to repeat hst:authenticated again on the Sitemap Item level again if you want to protect the Sitemap Item with extra constraints.

Hierarchical Authorization Check

Assume the following setup: On a Mount you have configured:

hst:authenticated: true
hst:roles: [staff]

And a piece of you Sitemap is as follows:

+ hst:sitemap
  + blog
     - hst:authenticated: true
     - hst:roles: [uberstaff]
     + _any_.html
       - hst:authenticated: true
       - hst:roles: [superstaff]
     + _any_

The above setup means that 

1. All authenticated users in role staff can access the Mount
2. All authenticated users in role staff and uberstaff can access /blog and /blog/2019, etc
3. All authenticated users in role staff, uberstaff and superstaff can access /blog, /blog/2019 and /blog/2019/myblog.html, etc

Multiple Roles

If on the Mount you for example configured

hst:authenticated: true
hst:roles: [staff, customer]

then an authenticated user in role staff or customer is granted access: HST Container checks the user's roles by the Servlet / JAAS standard APIs such as HttpServletRequest#isUserInRole(roleName), and only a single role has to match. 

Users or Roles

Instead of roles, you can also assign explicit users on an authenticated Sitemap Item or Mount. For example 

hst:authenticated: true
hst:users: [john, dick]

With the example configuration above, HST Container checks if the user's principal name is included in the hst:users property values. HST Container will retrieve the user's principal name using HttpServletRequest#getUserPrincipal().getName().

Finally, if both hst:roles and hst:users are present, then HST Container will look up both property values in order to see if the user can access the resource. If the user has any matching role or the user's principal name is included, then the user will be authorized. Thus for example the following configuration

hst:authenticated: true
hst:roles: [ staff, customer ]
hst:users: [ user1, user2 ]

then user1 and user2 are authorized even if they are not in role staff or customer, and for example user3 which is in role staff is also allowed.

Repository Level Authorization Integration

HST also provides repository-level authorization integration, meaning the JCR session used during the request will be tightly integrated with the authenticated user's subject.

To use this option, set the following boolean property for a mount:

hst:subjectbasedsession: true

With the configuration above, the JCR session during the request processing is created with the JCR credentials of the authenticated user's subject per each request. In this case, the JCR session is not borrowed from the internal JCR session pool. This allows authorization in the delivery tier at content level using security domains.

Optionally, the JCR session with this option can be stored in the HTTP session and reused in the following requests for more efficiency. To use this session stateful JCR session usage option, configure the following boolean property for a mount:

hst:sessionstateful: true

Note that this option should be used in limited environments, such as applications with limited users, because it can increase memory size at runtime when used without caution!