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.

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

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.

Configure the Advanced Permission modules in the app.js file:

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

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.

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 able to access.

At the top of the 'Permissions' section is a toggle that sets whether the group should have all admin permissions. If switched to "Yes," 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.

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. The "Role" column allows you to select between "Contributor" or "Editor". Selecting the "Contributor" role will allow the group to create and modify and delete draft content, but not publish it for public view. The "Editor" role will additionally allow the group to publish that content type. The selection in this column will be represented in the right four columns by either a greyed-out 'x' if not allowed, or by green checkmarks if permission is given for that action.

There are two special categories, "Users" and "Groups". Only toggling the top "Administer All" can change these permissions.

The second tab in this section is the "Members" tab. This tab lists the "Title" and "Username" or 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.

The third section allows for selecting what locales the selected permissions will apply to for the user. Note that these permissions are additive. For example, the user could belong to two groups, where the first group gives selected permissions in the English locale and the second in the French locale. Adding selected permissions in the Spanish locale at the per-user level means that individual will be able to exercise the selected permissions for all three locales. Note that these permissions might be for different documents in each locale. For example, the user might be able to publish images in any of the three locales, publish 'Articles' in English, but only edit 'Articles' in French. For the Spanish locale they wouldn't be able to change the 'Articles' piece-type at all.

If a user is given Editor or Contributor permissions for a certain document type in one locale, they will be able to see but not edit that type in other locales. They will be able to relocalize that document to a locale where they do have permissions to edit.

The third section displays the 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. In contrast, the latter can alter the 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 and topics.

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

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.

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 set the user pemissions to either "Contributor", or "Editor" with the difference being the ability to publish. These permissions will be reflected in the matrix to the right of 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 "Editor" permission for all pages at the user level, setting their permission to "Contributor" 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 a role of "Editor" or "Contributor", with permissions reflected in the matrix to the right of the group.

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.

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:

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