Taxonomy & Access Control

1. Drupal Permissions
2. Users
3. Importing Users
4. Setting CAS Associations
5. Roles
6. Creating a Role
7. Creating a Role via Duplicating an Existing Role
8. Permissions (by Role)
9. Managing Permissions
10. Content Access (by Taxonomy)
11. Assigning Content Access Permissions by Role, by Site Section
12. Creating New Site Section Taxonomy Terms
13. File Permissions
14. File Paths & Securing Existing Documents
15. Workflow and Revisions
16. Setting Up Pages for Review

Drupal Permissions

Permissions on a Drupal site consists of several different aspects.For the YLS site, permissions controls whether or not a particular user (typically based on their group membership) can view or edit pages, modules, and other aspects of the site.

Drupal features several concepts focusing around permissions:

1. User Accounts are the information stored in Drupal to identify an individual person.
   When a new user browses to the site without having logged in, they are treated as an 'Anonymous' user - they do not have a User Account.
2. Roles are used to group user accounts that share similar traits.One particular user account could have many roles.
3. Permissions dictate what users with a particular role are able to do.These apply at a global level (all content on the site), and consist of permissions such as 'view content', 'edit content', or 'manage menus'.There are some more granular permissions, such as by content type, where a user might only be able to create 'News' items.
4. Content Access (via Taxonomy) provides section-by-section permissions for the site.This functionality enables a particular role to be able to manage a site section (e.g. Corporate Law), but not other areas of the site.Essentially, Content Access narrows down the 'global' nature of Permissions-.
5. File Permissions are driven based upon user role, and are controlled based on the folder in which a particular file was uploaded.Changing file permissions potentially requires moving documents around in the file browser, and re-linking any existing links to the document.

Users

Drupal maintains a list of known user accounts.In the case of the YLS website, most of these user accounts will be assigned with CAS logins.

When a user is not yet logged in, they are known as an 'Anonymous User', and belong to the 'Anonymous User' role.After logging in, the user will be associated with their Drupal account, and will have the roles and permissions associated with that account.

Importing Users

Although Drupal provides the ability to create one user at a time, typically users will be created in batches.These can be accomplished via the People / Import administration interface.Typically, the import process requires a CSV or other data set for import.See the documentation for the User Import module for more information:

https://www.drupal.org/node/137653

Setting CAS Associations

The Drupal 'User Import' module does not automatically associate newly created users with CAS logins.Although this can be done through the Drupal interface on a user-by-user basis, it may be easier to conduct batch updates against the Drupal database.See the following resource for more information:

https://www.drupal.org/node/1261232

Roles

Each user account in Drupal can be assigned one or more Roles.Generally, roles match the concept of 'groups' of users, just that users can belong to many different groups.

A role encompasses a set of permissions enabling the user to use or manage an aspect of the site.For example, a 'News Department' role might enable the creation and management of News stories on the YLS website, but not other content pages.

A particular user can have multiple roles - they may have the 'News Department' role described earlier, but also have a role which grants them the ability to manage standard content pages.

Roles do not explicitly differentiate between 'site visitors' and 'content authors/administrators'.Instead, roles grant access to various actions via 'permissions'.These permissions might give a certain role access to the administration scenes, while other Roles (such as 1L students) would only be used for content access roles, and would differ little from what anonymous users are entitled to do.

Creating a Role

Roles can be managed on the People / Permissions / Roles administration interface.This page provides a listing of all current roles on the site, and provides the ability to create new roles.

Creating a Role via Duplicating an Existing Role

In general, it is recommended to start with an existing role when creating new roles via the Duplicate Role button at the top of the page.This automatically copies over all of the existing permissions (discussed in the next section) for the new role.

Permissions (by Role)

Permissions control what users with a particular role are able to do, on a global basis.Some examples include 'viewing any content', 'editing content', and 'editing a Tabs module'.Permissions apply on a global basis - the earlier example of 'editing content' would enable the user to modify any content on the site, regardless of what menu/area of the site the content lives within.That section-by-section management will be discussed in the next section, "Content Access (by Taxonomy)".

Managing Permissions

Permissions are managed through the People > Permissions administration area.The interface displays a list of Permissions vertically, and the various site Roles horizontally.Checking a checkbox grants that particular permission to that role.

Permissions can be managed at a granular level for each role.The list can be somewhat overwhelming at first, so it is recommended to compare the permissions for a new role to an existing role.In general, only content authors should have administrative permissions (creating, editing, deleting content, managing menus, etc.)

Site visitor roles should generally only have 'view content' and a few other permissions.See the existing Anonymous and Authenticated User roles as a basis for new visitor roles.

Content Access (by Taxonomy)

Content Access via Taxonomy controls access to individual pages or groups of pages.This is in contrast to Permissions (discussed earlier), which apply on a global level. This satisfies the additional need to be able to secure individual pages or groups of pages on the site based upon role.The Taxonomy Access Control module provides this capability.

First, every piece of content of the site, whether it is a Panel Page, a News item, or a content module (e.g. Photo gallery) must be tagged with a taxonomy term indicating its Permissions Section'.This taxonomy vocabulary provides a listing of all of the different areas of the site.If a piece of content is not assigned any of these terms, it will only be editable by administrators, and will be visible to any user.

The terms must be applied at every content level, not just pages, to fully implement the security model. This includes:

1. The page itself (e.g. Panel Page, News, Event, etc.)
2. Any content modules on the page (e.g. One Column Content, Large Promotion, Photo Gallery, etc.)
3. Any items referenced by the modules (e.g. Photo Gallery Slides, Tab/Accordion Sections, etc.)
4. Potentially, any items that may be fed into the page (Student Profiles, Alumni Profiles, etc.)

Assigning Content Access Permissions by Role, by Site Section

Content access by site section is managed based on user roles.For each Role on the site, we can configure whether or not to Allow or Deny access to a particular Site Section.These can also inherit - we can simply choose to 'ignore' (or really, 'inherit') permissions for that site section from the default permissions for that role.

Site Section permissions are assigned under Configuration / People / Taxonomy Access Control.

First, the system presents a list of roles whose content access permissions can be customized.You may need to 'enabled' access control for a role before customizing the roles.

Access Rules cover the ability to View, Update, and Delete content.Only the 'View' right is relevant for Roles that don't have any administration permissions, but the other two rights can be customized for content author roles.

Each rule can 'Allow', 'Ignore', or 'Deny' access.The 'Ignore' option simply means that the right is inherited from the default, or if for the default, defers to other roles the user might have. Finally, it would fall back on global Permissions, meaning that anyone can View, but only authors can Update/Delete.

When editing Access Rules for a particular Role, you have the ability to assign Defaults at the top, and then override those defaults for any number of Site Sections.The following screenshot depicts that Authenticated Users (anyone who is logged in) has access to View all site content by default, but is denied access to the CDO site section.

To specify different rules for another Site Section, locate the desired item under 'Permission Section' in the dropdown, click the desired rights, and click Add.Note that the dropdown contains all taxonomy terms across the site (in any vocabulary), so you need to choose those under the 'Permission Section' header.

One thing to remember is that the global Permissions, discussed earlier, also apply.If a particular role doesn't have any permissions to edit content, they won't be able to edit a particular Section's content either, even if that right is granted via Taxonomy Access Control.

Creating New Site Section Taxonomy Terms

Each 'section' of the site that will have differing permissions must be represented by both a user Role and by a Taxonomy Term (under the Permission Section vocabulary).

1. Create the Role under People / Permissions / Roles (use the Duplicate Role option)
2. Create the term under Structure / Taxonomy or Structure / Taxonomy Manager.
3. After creating the new Taxonomy Term, browse to it via Structure / Taxonomy / List Terms / Edit and expand the 'Permissions' field to assign it to the corresponding Role.

Granting Access to Everyone Except Users with a Particular Role

It is more complex than it first appears to 'deny' access to users with a particular role (such as 1L Students and the CDO section), but grant access to others.This is the result of two aspects of Drupal functionality:

1. All roles inherit from the 'Authenticated Users' role (except for the Anonymous Users role).This means that an 'allow' on authenticated users will be inherited in any other groups.
2. When a user has multiple roles, and those roles resolve to conflicting 'allow' or 'deny' permissions, 'allow' always wins.This means that even if you assign 'deny' to a specific user group, the fact that 'authenticated users' has an 'allow' means that the group has access.

Therefore, in order to allow access to a Site Section to all authenticated users except those of a particular group, you actually need to configure:

1. The 'authenticated users' role to Deny access.
2. All roles that should have access need to 'allow' access.
3. Optionally, the group that should not have access can also 'Deny' access, but this would be inherited.

File Permissions

The ability to view/download files (images, documents, etc.) can also be controlled for site visitors.

This provides content authors the ability to lock down access for particular documents to those with authorization.For example, viewing documents in the Career Development Office site might require the user to be logged in (i.e. have a CAS login).

By default, all files on the site are publically accessible to anyone (i.e. both anonymous users and authenticated users, belonging to any role).This includes files placed within the 'images', 'documents', and other directories in the file browser.

File permissions are controlled based upon the folder in which a file is placed.By default, all folders except for the 'private-documents' folder are publically accessible.Files located in the 'private-documents' folder require the user to be logged in (but not have any particular role).To upload a file that should be restricted to authenticated users, simply upload the file to the 'private-documents' folder.Links can then be created to the file either via File fields (e.g. photo gallery slide items) or the WYSWIYG content editor.

Files can also be secured based upon a user's roles (naturally, this also requires the user to be logged in).

1. Open the File Browser (accessible under People > Admin > Edit > File Browser)
   
2. Create a new Directory.This directory could, but does not necessarily need to be, a subdirectory of 'private-documents'.
3. Access Configuration > Media > Private files download permission.Click 'Add Directory'.
   
4. Enter the path to the newly created directory.
5. Under 'Enabled Roles', select the roles that should have access.All others will be denied.
   

6.Save the directory.You may now add files to the directory and they will be restricted to anonymous users and users without the specified role(s).

File Paths & Securing Existing Documents

As mentioned earlier, file permissions are based upon the folder (or path) of the file.Typically Drupal will automatically use a path that starts with '/system/files' (such as when creating a link in a WYSIWYG editor, or selecting a file for a photo gallery slide).This path will automatically resolve the user's permissions and show them the file if they have access.However, in the case that you are securing existing documents with links on the site, it may be necessary to change the path to start with '/system/files'.These existing links may start with '/sites/default/files', and these links will not work for secured files.

For unsecured files, either path will work, and they both refer to the same underlying file.The only time that you need to be concerned with the link format is when securing a file, and in that case, you always want the first path above.

IMPORTANT: If you are creating a secure folder outside root/private-documents/, an entry has to be made in the CAS settings: https://www.law.yale.edu/admin/config/people/cas under the REDIRECTION>Specific Pages area.Otherwise a redirect loop will result.

Other secure folders:
root/area/department/cdo/secure/*

Workflow and Revisions

1. When any author (including admins) save content it will no longer be published by default.
2. Instead, a new Revision is created in ‘draft’ state.
3. Basic Editors will only be able to set items to be in a ‘draft’ state or a ‘needs review’ state.They cannot publish directly.
4. When a basic editor marks an item ‘needs review’, an email goes to everyone in the Approvers role.
   Admins and ‘Approvers’ are able to mark items in Draft/Needs Review to be published. When this occurs, an email is sent back to the original author.
   Alternatively, the admin/approver can put it back into ‘draft’ state, indicating the change was declined.Again, an email is sent to the original author.
5. Administrators can override the default (draft) and set to immediately publish by using the ‘Publishing options’ field at the bottom of the node.
6. There is a tab on the Content editing screen for ‘Moderate’ which provides a revision history.It is possible to view each version and revert back to previous versions.
7. Please note: Do not click SAVE while the Moderation State is loading, must wait for ajax loading indicator to be complete before finalizing the moderation state by clicking SAVE.

Setting up pages for review

When developing pages that will need review by an audience outside OPA/ITS, the pages should remain unpublished.  The specific audience will need to be granted the permission to view unpublished content.  To assign the role:

1. Search for each user in /admin/people
2. Assign the role reviewer - unpublished
3. After review and the pages have been published, remember to remove this role

NOTE: The reviewer - unpublished role has a single permission assigned: Workbench Moderation > View all unpublished content