Folder-based authorization

🚧

Beta

Folder-based authorization is currently in Beta and should not be used in production scenarios.

By default, Content SaaS users are granted read or write permissions globally - meaning throughout the content repository - using functional roles assigned to them through Identity and Access Management (Content). Folder-based authorization allows for more fine-grained control or read-and-write privileges for individual users on individual content folders.

Folder-based authorization applies to users with the roles Content Author, Content Editor, and Site Editor, who are referred to on this page as "content users." It does not apply to users with the roles Site Admin and Site Developer.

Mechanism

A folder can be marked as "restricted." This has an immediate impact: access to that folder (and thus visibility of it) is denied for all content users. Users won't see the folder and they won't be able to navigate to it or to any of its subfolders.

To subsequently allow read and/or write access to specific users, two lists can be configured on every restricted folder:

• A list of users (usernames*) granted "read" access in this restricted folder. These users are able to read content in this folder and its subfolders, which automatically inherit read access.
• A list of users (usernames*) granted "write" access in this restricted folder. These users are able to read and write content in this folder and its subfolders. Write access automatically grants read access, and all subfolders inherit it.

* Usernames are typically email addresses.

Folder states

In the context of folder-based authorization, folders can be in either of the following 2 states:

• Unrestricted (default state): all content users can read and write content and navigate in this folder and all of its subfolders.
• Restricted: all content users don't have access to the folder. They cannot see and navigate in this folder (and consequently to its subfolders too).
  When a folder is restricted, it can further be in the following states:
  • Readable (for some users): specific content users have read access to this folder and its subfolders
  • Writable (for some users): specific content users have read and write access to this folder and its subfolders

Scenarios

Given the above states, the following scenarios are supported:

• Mark any folder as restricted and then allow specific users to read and/or write in it.
• Mark a (usually top or high-level) folder as readable for some users, and then some of its subfolders as writable.

The following scenarios are not supported at this time:

• Having a folder that is writable for a user but making some subfolder non-writable for the same user. Attempting to do so by setting the subfolder to be readable for that user will not achieve this, as the inherited 'write' privilege cannot be revoked.
• Restricting a folder but making a subfolder readable or writable. This isn't possible because restricting the parent folder means the users cannot navigate to it or any of its subfolders. The parent folder needs to be (at least) readable to these users.
• Restricting the "pages" folder or any folder configured to hold Experience pages. Although technically possible, this is not supported by the Experience manager and leads to inconsistencies in the UI.
• Restricting the channel root folder. Although technically possible, this is not supported by the Experience manager and leads to inconsistencies in the UI.

Configure folder-based authorization

You can manage folder-based authorization using the Folder Management and Content Batch Import APIs. The folder-based authorization information can be exported and imported as part of the folder payload used in both APIs.

The following folder attributes are used for this:

• A boolean attribute named restricted, denoting whether the folder is restricted. Setting this to false upon a folder update operation automatically clears any readUsers and writeUsers allow lists found on that folder.
• Two array attributes named readUsers and writeUsers that hold the lists of usernames with read and write access, respectively.

Example

Let's assume you want to restrict access to the folder /content/my-channel/content/articles and only grant read access to users [email protected] and [email protected], and write access to [email protected].

First, use the Folder Management API's Get folder endpoint to retrieve the folder's current attributes:

GET https://<your-content-host>.bloomreach.io/management/folder/v1//content/documents/my-channel/content/articles

Make sure to include your authorization token in the x-auth-token header!

You should receive a response similar to the following (no restrictions set in the example):

{
    "type": "folder",
    "path": "/content/documents/my-channel/content/articles",
    "displayName": null,
    "locale": "en_US",
    "allowedDocumentTypes": [
        "ALL_DOCUMENTS"
    ],
    "allowedFolderTypes": [
        "FOLDER"
    ],
    restricted: false
}

Make sure to save the value in the X-Resource-Version response header to use in the update request (see Updates and Conflict Prevention for details).

Then, use the Create or update folder endpoint to set the restricted attribute to true and specify the relevant usernames in the readUsers and writeUsers attributes.

Prepare the body of the request:

{
    "type": "folder",
    "path": "/content/documents/my-channel/content/articles",
    "displayName": null,
    "locale": "en_US",
    "allowedDocumentTypes": [
        "ALL_DOCUMENTS"
    ],
    "allowedFolderTypes": [
        "FOLDER"
    ],
    "restricted": true,
    "readUsers": [
        "[email protected]",
        "[email protected]"
    ],
    "writeUsers": [
        "[email protected]"
    ]
}

Send the request to the endpoint:

PUT https://<your-content-host>.bloomreach.io/management/folder/v1//content/documents/my-channel/content/articles

Make sure to include your authorization token in the x-auth-token header, as well as the most recent X-Resource-Version header value!

You should receive a 200 response status. Before the changes take effect for the users, they must log out and log back in.

Notes

• Usernames in the allow lists are not verified. It's possible to use incorrect or non-existing usernames in the allow lists.
• Folder-based authorization takes effect when a user logs in and remains the same throughout their active session. Configuration changes in folder-based authorization only take effect after the user logs out and logs in again.
• Copying a channel does not copy its folder-based authorization information. All folders in the new channel will be in the unrestricted state.
• Newly added content users are denied access to all restricted folders (as they don't appear in those folders' read/write allow lists).
• Folder-based authorization is only applied to content users with roles Content Author, Content Editor and Site Editor. Site Admins and Site Developers are not affected. Management of content via the Folder and Content Batch Import APIs is also not affected (no content is restricted from the service responses).
• Adding a user to both the list of read users and to the list of write users is redundant, as granting write access automatically grants read access too.
• Folder-based authorization is applied in the Experience Manager as well. Restricted content is hidden and non-writable content does not give the user the option to edit in the right side panel
• At this point, folder-based authorization can only be configured on /content/documents and its subfolders.