Folder-based authorization

🚧

Important

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 throughout the content repository using functional roles. Folder-based authorization allows for more fine-grained control over read-and-write privileges for individual users in individual content folders.

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

How does folder-based authorization work?

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

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

1. A list of users (usernames*) granted "read" access in this restricted folder. These users can read content in this folder and its subfolders, which automatically inherit read access.
2. A list of users (usernames*) granted "write" access in this restricted folder. These users can 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

Folders can be in the following two states in the context of folder-based authorization:

• 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).
  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

Supported scenarios

Given the above states, the following scenarios are supported:

• Mark any folder as restricted and 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.

Unsupported scenarios

The following scenarios are currently not supported:

• Having a folder writable for a user but making a 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

There are two ways to configure folder-based authorization:

• Using the Content permissions app in the Content SaaS webapp.
• Using the Folder Management API or the Content Batch Import API.

Using the Content web application

Role required: Site Admin or Site Developer

You can manage folder-based authorization in the Content permissions app.

1. Navigate to Setup > Content permissions.

   

2. In the folder tree, browse to the folder you want to configure permissions for.

   

3. In the Folder permissions dropdown, select Restricted.

   

4. Click on Change.

5. In the list of users, select Read or Read & Write next to a user to grant them the respective access right in this folder. You can use the search box and the navigation to find the users you are looking for.

   

6. Click on Apply.

Before the changes take effect for the users, they must log out and log back in.

Using the API

Role required: Site Developer

You can also 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:

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

1. Use the Folder Management API's Get folder endpoint to retrieve the folder's current attributes:

   HTTP

   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):

   JSON

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

2. 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).

3. 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.

   1. Prepare the body of the request:

      JSON

      {
          "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]"
           ]
      }
      

   2. Send the request to the endpoint:

      HTTP

      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!

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

Frequently Asked Questions

Are the allowlist usernames verified?

The allowlist usernames are not verified, so it's possible to use incorrect or non-existing usernames when using the API. You can prevent this by using the UI.

I made a folder restricted but users who don't have read or write permissions can still access it

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.

Does copying a channel copy its folder permissions?

Copying a channel does not copy its folder-based authorization information. All folders in the new channel will be unrestricted.

Do folder restrictions apply to newly added users?

Newly added content users are denied access to all restricted folders as they don't appear in those folders' read/write allowlists.

Are there any exceptions where folder-based authorization does not apply?

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. Content management via the Folder and Content Batch Import APIs is also not affected (no content is restricted from the service responses).

Do I need to add a user to both the read and write allowlists?

Adding a user to both the list of read users and the list of write users is redundant, as granting write access automatically grants read access.

Does folder-based authorization apply in the Experience manager?

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.