Best practices for Custom Permission Groups

Custom Permission Groups give you fine-grained control over the permissions in your Organizations. When creating a Custom Permission Group, there are some common pitfalls you can fall into. In this article, we will go over a few examples.

Resources#

A resource is something you can interact with in CloudCannon, such as an individual Site, Pull Request settings, or billing information. Each resource has one or more associated actions: Read, Write, or Create. In CloudCannon, you select which resources you want members to have access to using the resource permission tree.

Minimum set of resources required to view a Site in CloudCannon

There is a minimum set of resources required to view a Site in CloudCannon.

Groups will need a permission containing the following resources for each Site you want members to access: site:details:read, site:build:details:read, and site:sync:details:read. If you have connected your Site to a DAM, you will also need site:dam:read.

File globs#

A file glob is a pattern used to identify matching files. File globs look similar to a file path with a mix of literal text and special characters such as * and { }. In CloudCannon, you can specify read or write access to specific file globs in a Custom Permission Group for fine-grain control over reading and editing site files.

Here are some common pitfalls when creating file globs.

Adding a Permission file glob narrows access to matching files

Adding a file glob to a Permission narrows it to files that match the glob pattern(s), excluding all others. Because of this, you can unintentionally remove access to files when you begin adding file globs to a Permission.

By selecting site:file:read or site:file:write in the resource tree and specifying no file globs, you allow the members of a Permission Group to read or write all files within your permission scope. However, as soon as you add one file glob to the Permission (or Exception), CloudCannon will change which files they can access. For Permissions, CloudCannon will limit members of a Permission Group to only files that match the glob pattern(s). For Exceptions, CloudCannon allows members of a Permission Group to access all files except those that match the specified glob pattern(s). When used together, Permission file globs provide access to specific files, to the exclusion of all others, and Exception file globs limit access within the files that match the Permission pattern.

Let's walk through an example.

You have a Custom Permission Group with the Permission site:file:write. This allows members of that Group to read and write any file on the Site (as permission to write implicitly includes permission to read). By adding the content/**/* file glob to your Permission, members of the Group will lose read and write access to any file that is not in the content collection. Without permission to read other files, all other collections on your Site will not appear in CloudCannon.

To avoid this pitfall, carefully consider what files your Group members need access to and include a file glob for all these files.

Multiple file globs are necessary to edit a single file

When giving access to a small number of files on your Site, you should consider how many file globs you need to achieve your goal. Some file globs are not immediately obvious but are required for CloudCannon to function as intended.

You should also allow access to:

• The Site icon file.
• The Schemas folder or specific Schema for any files you want Group members to be able to edit or create.
• Any folders in your repository for storing or uploading images and videos.

Exceptions carve out files without needing a matching permission glob

An exception file glob removes only the files it matches — it does not switch the permission into whitelist mode. So if you select site:file:read or site:file:write in the permission resource tree (a permission with no file glob, covering every file) and add an exception file glob, members keep access to every file except those the exception matches.

For example, a permission with site:file:write selected plus an exception for the file glob secrets/** lets members edit every file except those under secrets.

You do not need to add a **/* permission glob for the exception to work — a globless site:file:read or site:file:write permission already covers all files, and the exception carves out from it. Remember that a read-level exception glob also removes write access to the matching files, while a write-level exception glob leaves read access in place.

Specifying files but not subfolders

File globs include special characters such as * and { }. The * character matches any file within a single folder. without crossing folder boundaries, while /**/ matches any number of folders. When specifying a file, it is important to account for any subfolders in your Collection.

For example, the file glob /posts/* will match any file located immediately within the root of the “Posts” Collection, /posts/*/* will match any file located exactly one subfolder deep, and /posts/**/* will match any number of subfolders deep in your Collection. A glob ending in /**, such as /posts/**, is equivalent to /posts/**/*.

Adding file globs but forgetting the read permission for your CloudCannon Configuration File

You need permission to read the CloudCannon Configuration File to see Collections in your Site Navigation. As soon as you add a Permission file glob, CloudCannon narrows the generic site:file:read or site:file:write options to only files that match one of your Permission globs. If your globs do not cover the CloudCannon Configuration File, members of your Custom Permission Groups will be limited in their ability to use Sites on CloudCannon.