Advanced Permission

This module provides more granular control over content permission. It allows the creation of custom groups with proscribed abilities and the ability to assign users to as few or as many groups as desired.

This README applies to Advanced Permission version 3.x.x. For version 2.x.x, which used roles like 'Contributor' and 'Editor', see the Notion page.

Installation

To install the module, use the command line to run this command in an Apostrophe project's root directory:

npm install @apostrophecms-pro/advanced-permission

Configure the Advanced Permission modules in the app.js file if using this in a single-site project:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms-pro/advanced-permission-group': {},
    '@apostrophecms-pro/advanced-permission': {},
  }
});

If you are using @apostrophecms-pro/advanced-permission in a multisite project, you can add these modules as outlined above to both the site/index.js and dashboard/index.js files. This will enable advanced permission for both the dashboard and all of your individual sites. If your dashboard currently uses the privateDashboards: true feature, you must set that to false before starting to use advanced permissions in the dashboard. This setting doesn't affect the use of advanced permission for sites.

Note: If upgrading from a version that did not include per-locale permissions, please see the important Adding a new locale for the first time or upgrading @apostrophecms-pro/advanced-permission section near the bottom of this document.

Usage

The typical workflow for this module is to add one or more groups with specific permissions. Then users are assigned to one or more groups. Additional permission can be set on an individual document basis.

Groups

Activating the Advanced Permission module will result in a menu added to the admin bar to create new groups. Clicking on this opens a modal that allows the addition of new groups.

Clicking on the "New Group" button will bring up a modal for creating a new group with two settings tabs.

The "Basics" tab has several sections. At the top is a section with a field for the group's unique name in the Title field.

The "Admin Permissions" section contains a toggle that sets whether the group should have all admin permissions. If toggled on it will allow the new group to create, modify, delete, and publish all content on the site, including creating additional users and groups. Only users who are completely trusted to manage other users and their permissions should ever be added to such a group. Note, giving a group admin permissions overrides per-locale permissions. That group will be able to work with documents in any locale and the Locale Permissions section will disappear.

The next section, "Locale Permissions", contains a drop-down that is prepopulated with all of the locales for the site. It allows you to select one or more locales for that group to be given the checked permissions.

Within the Permissions grid, the left "Content Type" column is prepopulated with all the categories of content that can have permissions applied. This will be project-specific and includes pages, custom piece types, and attachments. Permissions for each document type are added by checking the boxes to the right of each content type. There are also toggles to add all permissions (except group and user permissions) or an entire column or row of permissions.

The checkboxes can be in one of four states. They can be open, as they are for the "Create" permission for "Pages" in the example, indicating no permission. Checked with a dark purple background if permission is explicitly given for that action, or a light purple background if the permission is implicit, for example, if the document has autopublish: true. This is shown, respectively, for the "Archive" and "Publish" permissions of the "Images" content type. Finally, it can be a solid grey if the document type can not be given that permission, for example, if the document is a singleton or the permission depends on another permission in the grid. This is shown for the "Create" permission for the "Global" content type. Hovering over grayed-out boxes will cause a tooltip with clarification to appear if the permission is dependent on another permission in the grid.

Giving a "Create" permission for a content type will also allow a member of the group to edit, submit a draft, and delete any drafts of their own content. However, they will not be able to modify any other user's content, even if they are part of the same group. You need to give "Modify" permission to allow this.

The second tab in this section is the "Members" tab. This tab lists the "Title" and "Username" of all users who are members of the group. Additionally, it lists all groups of which that particular user is a member.

Users

Activating this module will also alter the "Users" modal. In the permissions tab, there will now be four sections. The top-most is a toggle that disables site log-in for the user.

The second section allows for selecting groups created through the "Groups" menu. Each user can have any number of groups assigned. These permissions are additive.

The third section enables the selection of additional locales not already included at the group level. These locales are cumulative. For instance, if one group permits modifying the article piece-type in the English locale, and another grants rights to edit Pages in the French locale, adding those two groups will allow the user to edit both those document types in both locales. Adding a user-level locale extends these effective permissions to the new locale.

If a user has permission to perform at least one action, even if only on a per-document basis, for a certain document type in one locale, they will be able to see but not edit that type in other locales. They will have permission to localize that document to the locale where they do have permission. If there is associated content that the user doesn't have permissions for it will not be localized.

The final section displays the effective permissions matrix resulting from the groups that are applied to the user.

Example

One possible use case is to assign roles to staff photographers and photojournalists, where the first kind of user is only allowed to add photos to the site and modify them. In contrast, the latter can modify all the site images plus publish articles using those photos. For this use case, you could have two groups.

The first group allows for editorial control of images and image tags.

The second group allows for editorial control of articles.

To add a new photojournalist, you can add both groups to the same user giving complete editorial control over images, image tags, and articles.

Per-document permission

The Advanced Permission module also allows admins to set the permissions for specific pages and pieces, rather than whole categories of page- or piece-types. The permissions tab in these cases is located in the editing modal for the individual document. Any permissions added in the per-document permissions apply to all locales for that page or piece.

This image shows the 'Permissions' tab for a page created with the default template. Editing the permissions here WILL NOT give the selected user(s) permission to edit all pages made with the default page-type template, only permission for this specific page. If you want the user to move a page in the tree, they must have general page "create" permission. It isn't sufficient to give them per-document permission. However, a user with at least "create" permission for any page can restore any archived page, even if they don't have any per-document permission for the archived page.

User Permissions

The per-document permissions tab is broken into two sections for pieces and three sections for pages. The top section allows the selection of individual users. Adding an item will cause two input fields and a matrix showing the impact of the selections to appear. Clicking in the first field will bring up a selection list populated with a list of users. Depending on how many users your site has, this might include all users or just a selection of them. If the desired user doesn't appear on the list, typing in the input field at the top of the list will refine the list.

The second input field allows you to add "Modify", "Archive", and "Publish" permissions for the user. To remove permissions from a user, click the trashcan icon to the right of the user's row.

Permissions added through the per-doc permissions panel do not overrule permissions given through the user permissions. If a user has "Publish" permission for all pages at the user level, setting their permission to only include "Create" and "Modify" on a specific page will not remove their ability to publish that page. This will not be reflected in the matrix of permissions within the per-document permission panel.

Group Permissions

The second section of the permissions tab is structured almost identically to the top section, with the first input field showing a list of groups created by the Groups Manager, rather than individual users. Again, each group can be assigned "Modify", "Archive", and "Publish" permissions.

Like the User Permissions, the Group Permissions will not override permissions given to the Group in the Group Manager.

Apply Permissions

The bottom section of the permissions tab only appears when you are setting the permissions for a page-type document. When this box is checked, permissions are copied to the subpages on a one-time basis. They may then be edited on the individual page level. If any permissions are subsequently changed that you want to be extended to all subpages, such as removing permissions from a user, you must click this box again before saving. Otherwise, the change in permissions will only apply to the current document. Changes made within the permissions tab of a subpage will be discarded if the parent page permissions are applied to all subpages.

Adding new permission types

In addition to the core permissions, new permissions can be created using the top-level permissions object of any module. This will allow for the selection of the new permission for that document type. The new permission can be added for multiple document types by configuring an Apostrophe core module at project-level. For example, adding the permissions object to the @apostrophecms/piece-type module to add the permission to all pieces. Much like the fields object, this object takes an add property which contains an object of the named custom permission objects. Each new permission object is named for the new permission and can take three properties.

The label property will determine what is shown at the top of the group or per-document permission manager.

The optional requires property determines whether the ability of the admin to select this permission is dependent on any other permission in the grid. For example, requires: 'publish' would require that the admin selects the "Publish" permission for the document or document-type before they could be select the new permission.

The optional perDoc property takes a boolean and defaults to false. If set to true, it allows this permission to be added to individual documents in either the user or group permissions.

module.exports = {
  extend: '@apostrophecms/piece-type',
  options: {
    label: 'Product'
  },
  fields: {
    add: {
      productTitle: {
        type: 'string',
        label: 'Product Title'
      },
      productDescription: {
        type: 'string',
        textarea: true
      },
      productPrice: {
        type: 'float',
        label: 'Product Price',
        editPermission: {
          action: 'pricingField',
          type: 'product'
        }
      }
    },
    group: {
      basics: {
        label: 'Basics',
        fields: [
          'productTitle'
        ]
      }
    }
  },
  permissions: {
    add: {
      pricingField: {
        label: 'Pricing'
      }
    }
  }
};

editPermission: limiting access to a single field

Once you create your custom permission it can be used to determine if a user can view and edit a selected field using the editPermission schema field property. This property takes an action and a type. The action should be set to one of the built-in permissions, like create, or any custom permission that you create. The type should be set to the module that permission is associated with. For core modules make sure to prefix the module name with @apostrophecms/ or @apostrophecms-pro/.

From the example above:

// other module fields
productPrice: {
  type: 'float',
  label: 'Product Price',
  editPermission: {
    action: 'pricingField',
    type: 'product'
  }
}
// remainder of the module code

The productPrice field can only be edited by a user that has been granted pricingField permission for the product piece-type by the admin.

You can also check to see if a particular user has a custom permission when setting up routes using self.apos.permission.can(req, 'custom permission name', doc). This will only return true if the user was given that custom permission.

Limitations of editPermission

• perDoc: true is not compatible with the editPermission feature. Instead, grant the user per-document permission to "modify" the document, and then use group membership to grant custom permissions that are checked by an editPermission property.

Migration

A migration will automatically occur the first time when running a project with the Advanced Permission module activated.

It will create a group for each role found in existing users and will attach them to the group corresponding to their role field.

Adding a new locale for the first time or upgrading @apostrophecms-pro/advanced-permission

Under two circumstances you will need to take extra steps to set permissions.

1. If you add an additional locales to a site with only one site enabled and the advanced permission module installed.
2. If you upgrade the module from a version that did not have per-locale permission.

In both of these cases, all of the non-admin users and groups will immediately lose their permissions until they are granted access to edit in one or more locales. Admins will still have access and can address this by giving control of one or both locales to appropriate users and groups in the system.

Tasks

rollback-advanced-permission

This task will remove all @apostrophecms-pro/advanced-permission-group pieces and their relations.

On the command line run:

node app @apostrophecms/permission:rollback-advanced-permission

Then remove @apostrophecms-pro/advanced-permission-group & @apostrophecms-pro/advanced-permission from app.js.

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    // Delete the two lines below
    // '@apostrophecms-pro/advanced-permission-group': {},
    // '@apostrophecms-pro/advanced-permission': {},
  }
});

add-admin

If creating a brand-new site with this module present from the beginning, there are two very important command line tasks to know about in order to gain access to edit your own site:

1. @apostrophecms-pro/advanced-permission-group:add-admin admin, which adds an admin group named admin.

2. @apostrophecms/user:add admin --group=admin, which creates a user named admin and adds them to the admin group.

   Note that the behavior of this second task is modified in the presence of the advanced permission module: it adds the new user to a specific group, rather than granting a specific role.

Usage for a single site project:

node app @apostrophecms-pro/advanced-permission-group:add-admin admin
node app @apostrophecms/user:add admin --group=admin

Usage for a multisite project:

node app @apostrophecms-pro/advanced-permission-group:add-admin admin --site=dashboard
node app @apostrophecms/user:add admin --group=admin --site=dashboard