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:
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.
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:
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:
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:
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.
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.
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:
Access Control Lists in Joomla! can be found here:
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:
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:
See the Wordpress integration chapter toward the end of this book for full details of Wordpress permissions and ACL.
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.
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:
Once the roles are configured, you can begin to assign them to users. In CiviCRM this is done in two steps:
The third step is where the ACLs are finally created. They can be broken down into the following questions:
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:
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:
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.
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.
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.
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.
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.
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.
This access right should be assigned with care, and only to trusted roles. The permission grants access to:
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).
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 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.
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.