Permissions and access control

What are Access Control Lists (ACLs)?

Access Control Lists are collections of rules which define access to various areas of the system. Through building user roles and assigning people to them, you can choose to allow and restrict the role's access to:

Different areas of CiviCRM (e.g. CiviContribute, CiviCase and CiviMail) to reflect the tasks the user is responsible for; why clutter the interface they see with tools they do not need?
Records within the system, and how the user can interact or operate with them (e.g. view, edit, delete)

To manage this, there are two places where ACLs can be created: in the Content Management System - or CMS - CiviCRM is integrated with (e.g. Drupal, Joomla! or WordPress), and native ACLs in CiviCRM itself. Depending on your requirements, you may wish to use one or both, as they each have different purposes.

How are CMS and CiviCRM ACLs different?

The main distinction between the two is that CMS access control lists can 'turn off' entire sections of CiviCRM to user roles who do not need them, such as CiviMail, while native CiviCRM ACLs cannot. They also allow you to restrict the user's ability to view, edit, add and delete records such as contacts, events and contributions. However, this is an 'all or nothing' approach to record permissions; you cannot differentiate between contacts who fall into different groups, for instance. Native CiviCRM ACLs are more advanced in this respect as they allow you to, amongst other things, also limit access to view, edit, create, delete and search:

Groups of contacts
A profile (this is a collection of existing and/or custom fields, see "Profiles")
A set of custom fields
Events (e.g. a user may access one event, but not others)

The CMS access control lists should be used in most scenarios, except for when you wish to enforce more granular access rights, in which case a combination of the two may be the most effective approach.

To clarify, here are two of examples of times when CiviCRM ACLs should be used instead of those in Drupal, Joomla! or WordPress:

An organisation has a head office, and three regional offices spread across the country. The event director working from the central office must be able to view all events across every office, but the event coordinators reporting to the director and local to each regional office are only to have access to view and edit their own events. Since a CMS access control list would only be able to restrict access to view/edit/add/delete all or no events, a CiviCRM ACL must be used.
Two sets of custom fields have been built, one for a team of employees working in Paris managing a group of volunteers, and the other collecting donor information in London. Each team should only be able to access data held in their own set of custom fields, however, a CMS access control list could only give them access to all of the custom information, or none of it. In this case any CMS rule controlling access to custom fields should be disabled, and a CiviCRM ACL used instead.

Authenticated and anonymous/public roles

You will encounter both these role types as you work with the access controls, and it is important that you understand the definition and security implications of each. If you are not familiar with these terms in this context, please read the following before continuing.

The authenticated role refers to a visitor to the website/CRM who has logged in with an account that they have registered themselves, or has been created on their behalf. This is the default role for all new user accounts, and cannot be deleted. Please bear in mind that each content management system and CiviCRM come with a role for authenticated users that has a minimal level of access by default, which may or may not be suitable for your purposes. You can alter the permissions authenticated users have, but you must consider the implications of this very carefully. For example, if you need to give some logged in users additional access to areas of CiviCRM like creating contacts, we recommend you create a new role with this ability. However, if all of your authenticated users must have this level of access (and only if this is the case), you could add that permission to the "authenticated" role.

Conversely, the anonymous role applies to all visitors to the website who have not logged in. By default, their access to CiviCRM data and functionality is strictly limited to only a handful of actions:

Registering for events through online forms
Viewing event information and participants
Making online contributions/donations
Subscribing and unsubscribing from mailing lists

From a security standpoint this is prudent for an 'out-of-the-box system, however, depending on how you use the system, new forms and functionality that you go on to enable for anonymous users may not function correctly until a few additional permissions are given. For a list of the most common cases when a new permission must be given, please read "Important ACL settings" below.

Drupal and Joomla! ACLs

The access control lists in both Drupal and Joomla! offer the same range of permissions, but each are found in different places, and differ slightly in appearance.

Finding ACLs in Drupal

To access Drupal's Access Control Lists, go to the Drupal menu, choose the option "People" and click the "Permissions" tab in the top right corner of the pop-up window. Here you will find a long list of all possible possible operations/actions a user could perform in CiviCRM and Drupal, with columns for each existing role type. Unchecking an option in one of the columns will remove that role's ability to perform the action.

You may create new roles and edit all existing ones, except for anonymous and authenticated; as both are integral to both systems, they appear locked and cannot be changed. To edit roles, while in the "Permissions" tab click the button "Roles" toward the top right of the page.

Roles can be assigned to users in the following ways:

Open a user's contact record (a contact in CiviCRM with a user account), hit the "Actions" button at the top and select "User Record" from the menu. When the next screen appears, click the "Edit" tab (top right) and then scroll down to the section titled "Roles"; here you may change their level of access.
As an administrator, go to the Drupal menu and select the option "People". When the list of active users appears, click on the desired name to open their Drupal user profile, go to the "Edit" tab at the top-right of the page, and then scroll down to the "Roles" section.

Finding ACLs in Joomla!

Access Control Lists in Joomla! can be found here:

Log into the Joomla! administrative portal
Go to the "Components" menu and select "CiviCRM" from the list
In CiviCRM's menu, navigate to Administer > User and Permissions > Permissions (Access Control)
Click the option "Joomla Access Control" at the top of the list

Unlike Drupal, you cannot edit or add to the existing list of user roles, however to edit the permissions they currently have, simply click on one the role's in the table to expand the list of possible actions/operators.

Joomla! has a different method to assigning permissions, in that each role is either a parent or child to another role, where child roles (those lower in the table) inherit the permissions set for those above them. Therefore, when editing the permissions assigned to a role in the table, you may choose between:

Inherited: if the role above was given this permission, it will also be able to perform the given action
Allowed: users in this role are allowed to perform the operation
Denied: users in this role cannot perform the action

Finally, to assign one of these roles to a user, or change their existing role, ensure you are logged in as an administrator and either:

Go to the user's contact record in CiviCRM, click the "Action" button and select the option "User Record". A section called "Assigned User Groups" will be available to change roles.
Within the Joomla! administrative portal, under the "User" menu click "User Manager". All available users will be listed, and clicking on a name will open a screen with the option to change their account settings, including role.

WordPress ACLs

See the Wordpress integration chapter toward the end of this book for full details of Wordpress permissions and ACL.

Native CiviCRM ACLs

As discussed earlier, CiviCRM ACLs are a more advanced and granular way of managing user access to records through contact groups, assigned to ACL roles. While an access control in the CMS can 'turn off' visibility of entire sections of CiviCRM, and determine whether a user can view/edit/delete/create data in the different areas of the system, they cannot sub-divide these rules into access to different record types. For example:

A charity based in Chicago has three regional offices, and needs to give its fundraising staff the ability to create and edit contact records for prospective donors. They have decided that the fundraising department in each office can only have access to its local contacts. While the permission "add contacts" can be granted to authenticated users in the CMS (Drupal, Joomla! or WordPress), if "view all contacts" and "edit all contacts" were also assigned in this way, there would be no way to differentiate between the three groups of donors (locations). This could only be achieved with a CiviCRM ACL.

To begin, go to Administer > User and Permissions > Permissions (Access Control). This screen will link you to the CMS access control list, and the three steps to managing those native to CiviCRM.

1. Manage Roles

This is where you can create ACL roles. By default you will have "administrator" and "authenticated" (logged in), but only the administrator role may be edited; "authenticated" is a reserved role and core to the system.

Clicking "Add Acl Role" will present a screen for creating a new role with the following options:

Label: this is the name of the role, and will be visible to users
Description: create and format a description of the role
Weight: give the role a number to determine its place in the list (e.g. "1" places the role at the top, while "20" might send it to the bottom; lower numbers appear before higher ones)
Enabled?: is the role active or not? If you disable this option, functionality may cease to work for some users

2. Assign Users to CiviCRM ACL Roles

Once the roles are configured, you can begin to assign them to users. In CiviCRM this is done in two steps:

First create an access control group for a selection of users that are to have the same level of access. There are multiple ways to do this, outlined in the chapter "Groups and tags".
The ACL contact group can now be assigned to a role. Click the second step on the access control menu screen ("Assign Users to CiviCRM ACL Roles") and hit "Add Role Assignment". Complete the following:

ACL Role: select an available ACL role
Assigned To: choose a contact group to assign to the role
Enabled?: is this assignment active or not?

3. Manage ACLs

The third step is where the ACLs are finally created. They can be broken down into the following questions:

Which role will have permission to perform this action?
What is the action/operation? Is it the ability to view/edit/delete/create, etc?
Which set of data can the action be carried out on?

To begin creating these ACLs, return to the Access Control screen (Administer > User and Permissions > Permissions...) and click "manage ACLs". A list of existing controls will be displayed, likely including one for administrators giving them permission to edit all contacts in the database. To add a new one, click "Add ACL" and fill in the following:

Description: write a clear description of what the ACL does
Role: choose a role to assign the ACL to from the drop-down list
Operation: select the action this role is allowed to perform (e.g. view, edit, create, delete...)
Type of Data: choose the data type the operation relates to:

A group of contacts
A profile
A set of custom fields
Events

Group/profile/custom data/event: this is where you select the specific group of contacts, profile, custom data set of event
Enabled?: is the ACL active?

Important default ACL settings, and when to change them

Certain features in CiviCRM require users to have a minimum level of access. By default, authenticated and anonymous/public roles ship with a set of permissions which are minimal, whilst providing a standard level of access that enables users who fall into those roles the ability to carry out common tasks (see "Authenticated and anonymous/public roles" above). However, as you configure the system further and wish to give these visitors the ability to interact with the system in new ways, you will need to change the permissions assigned to the roles for the functionality to work correctly.

The following are common scenarios where you would need to alter the access control lists, and what the changes should be:

Taking online contributions

If you plan to use CiviContribute and want to allow online contributions, enable the permission "make online permissions" in Drupal and Joomla!. Be sure to assign this permission for the "anonymous" or "public" role if you wish to give un-authenticated visitors the ability to make contributions.

Viewing event info and registering for events

Are you using CiviEvent and intend to build online event registration pages for the public? For them to be able to use the registration forms, "anonymous" or "public" roles must be given the permissions "view event info" and "register for events" in Drupal or Joomla!. Note that this will give all visitors the ability to register for any event. If you wish to give only specific users the ability to view or register for some events, you must use a CiviCRM ACL, allowing a role "view" access to events if they should only be able to view event information, and the "edit" permission if they can register. However for this to function, the CMS "register for events" ACL must be disabled, as it will override these settings.

e.g. A charity holds occasional fundraising events for the public and separate evening dinners for some of its corporate donors. Any visitor to the website can register and participate in a fundraising event, however the dinners are private are must only be available to some of their donors. In this instance, CiviCRM ACLs should be used instead of the CMS rule "register for events" as they can specify the specific events each group of users can access.

Editing profile data in online forms

Profiles are collections of default and custom fields, and can be used in online forms to collect additional information from visitors, or build searchable directories (see "Profiles").

If you have a standalone profile in an online form used to search for and edit data in CiviCRM (e.g. not part of an event registration page), only authenticated users may edit. The permission "profile edit" can be given to the anonymous role, but visitors who are not logged in will still be unable to edit the data unless they have a checksum (a unique URL to one page where they may edit their own data; read "Everyday tasks" in the email section for more information). For checksum tokens to work, anonymous users must have the "profile edit" permission.

Collecting data from anonymous visitors using profiles

If you have built profiles to collect data from anonymous visitors through online forms (e.g. event registration pages, contribution pages and standalone profile forms), the permission "profile create" will need to be given to the "anonymous" role. Furthermore, should the profile contain any custom fields, an additional permission will need to be given, depending on the circumstances. Read "Accessing custom data" below.

Creating searchable directories for the public

Profiles can be used to build searchable directories; a form of search criteria able to gather a list of results from the database (e.g. finding organisations held in the database by location). If you would like to give all anonymous users access to search pages published on the website, check the "profile listings" option for the "anonymous" profile.

Profile view

Where profiles have been embedded within online pages (e.g. to display an organisation's name, description and contact details from the database), the visitor must have the permission"profile view" to see it.

Using the "Profile listings and forms" permission

This access right should be assigned with care, and only to trusted roles. The permission grants access to:

Add data through profiles in online forms
Edit data displayed in standalone profiles on public pages, if the option is given (e.g. contact information)
Use public searchable directories

Where possible, each of these access rights should be assigned to a role separately, not through this 'allow all actions' permission. "Profile listings and forms" is not enabled for the "anonymous" and "authenticated" roles by default.

Note that if this role were given to anonymous users, in order to edit data, the vistor must either be logged in or using a checksum token (see "Everyday tasks" in the section on email).

Accessing custom data

If custom data fields have been used on an online form or within profiles, the user will not be able to interact with it unless they have been given permission to view and/or edit custom data. There are two ways of assigning this ability:

Enable the "access all custom data" permission against the roles you wish to give both view and edit access. If this were given to the "anonymous" role, for example, they would be able to view and edit all custom fields in online forms (e.g. custom data fields within a profile that has been incorporated into an event registration page). However, this is an 'all or nothing' approach.
Alternatively, CiviCRM ACLs can be created to give roles access to only specific sets of custom data fields. Use this option when you want to give groups of users access to different sets of data, e.g. a team in Amsterdam may only have access to custom volunteer fields, while the head office in Scotland has access access to both custom volunteer fields and custom donor fields. Note that these ACLs will not function if the "access all custom data" permission is used in the CMS; that permission in Drupal or Joomla! will override these settings in CiviCRM.

Accessing uploaded files

Enable the "access uploaded files" permission for any role that needs to view images, photos and files attached to CiviCRM records and pages. Be sure to assign this permission to the "anonymous" role if you want visitors to see photos attached to contact records, personal campaign pages, documents intended for public consumption, etc.

Giving users the ability to view their contact dashboard

You can provide authenticated (logged in) users with access to a screen where they can review the mailing groups they have subscribed to, their contributions, memberships and event registrations (where applicable). Assign the "access contact dashboard" permission to roles whose users are to be given access to this feature. Do not enable this for the "anonymous" role.

EDIT