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

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 addition of new groups.

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

The "Basics" tab has three sections. At the top is a field for the group's unique name. The next field 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.

Finally, there is a "Permissions" section. 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 by 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 three 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 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.

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

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