Access Control Lists - Giving Your Users Access to CiviCRM

Below, we've laid out the steps for creating ACL's for a specific purpose. For more generic instructions, check out Greg Heller's (CiviCRM guru from Civic Actions) excellent article on how to create ACLs http://civicactions.com/blog/2011/feb/18/civicrm_access_control_acls_dem....

What are Access Control Lists?

One of the powerful features of CiviCRM are ACLs (Access Control Lists). With ACLs you can give your users (staff, volunteer coordinator, board member) access to only certain portions of CiviCRM, allowing them to see and update only that which you want them to see and update.

Granting Permission & Access Control in CiviCRM

What are 'Permissions?'

Permissions in the computer world are basically ways of saying 'this person (i.e., user) can see this information' or 'this person can see that information' or 'this person can see all the information' or 'this person can't see any information.'

Think of it like locks and keys on your file cabinet. Suzy has a key to get into the drawer that contains the contribution records and Bob has a key to get into the drawer that contains the volunteer records and Jane has keys for every drawer.

Drupal Permissions & CiviCRM ACLs

When working with CiviCRM access control, it is important to remember that Drupal permissions and CiviCRM ACLs (permissions) interact with one another and that Drupal permissions ALWAYS override CiviCRM permissions (ACLs).

Drupal permissions are much broader than the finer-grain access that can be created with CiviCRM ACLs. In order to give this finer-grain access we have to remove the broad Drupal permission (such as 'access all custom data') and add back the finer-grain CiviCRM permission (such as only 'volunteer hours' or 'volunteer skills and information' custom data).

In other words, if we set up ACLs in CiviCRM for our Drupal volunteer coordinator role, but haven't turn off 'access all custom data' in Drupal, then the volunteer coordinator role will still be able to see all custom data because Drupal's permissions override CiviCRM's. Make sense?

This is all to say that GingerFeet has to make sure that permissions are setup properly in Drupal for the user role you want to assign ACL permissions to so that there are no barriers to the ACLs working properly. If you wish to grant access to your users, please contact us at info@gingerfeet.com.

Use Case Scenario:

You want your Volunteer Coordinator to update the volunteer hours and view their volunteering information without giving them access to either contribution information or confidential homeowner interest information.

Here are the specifications for the Volunteer Coordinator role. The Volunteer Coordinator role must:

Outline of Steps

  1. Setup a Drupal user assigning them the 'volunteer coord' role.
  2. Create a CiviCRM Group that has access control.
  3. Add the CiviCRM contact(s)/Drupal user(s) who has the 'volunteer coord' role to the Group.
  4. Create an ACL Role that acts as a container for this group's permissions.
  5. NOTE: This is a CiviCRM Access Control Role...NOT the Drupal role. (Try not to be too confused!)

  6. Create ACLs (i.e., permissions) that gives this group access to view/edit the:
    • CiviCRM Volunteers group
    • Volunteer Hours/Tracking custom data
    • Volunteer Availability custom data (If so desired)
    • Volunteer Interests custom data (If so desired)
    • Volunteer Skill Set custom data (If so desired)

Drupal Users

First Steps

You will need to do two things before you create your ACLs:

  1. Set up your user with a Drupal account (assign them to the 'volunteer coord' role in Drupal) and a CiviCRM contact record. Make sure that your Drupal user account and CiviCRM email matches – i.e., that the Drupal user and CiviCRM contact are connected/one-and-the-same user.
    1. In Drupal, go to User Management → Users → Add User.
    2. Enter a Username.
    3. Enter an E-mail address. If your user already exists in your CiviCRM database, make sure that this email matches the primary email address in the contact record. If this user does not exist in your CiviCRM database, setting them up here will add them.
    4. Enter a Password. GingerFeet requires passwords that are at least 9 characters long and contain upper or lowercase letters, numbers and special characters.
    5. Leave the status as Active.
    6. Check the appropriate Roles – in our example it would be volunteer coord.
    7. Check the Notify user of new account if you want Drupal to send an email to the user that you are setting up this account.
    8. Enter the Name and Address information for the user/contact. You are required to enter the First Name and Last Name. If this user already exists in your CiviCRM database, try and make sure you use the same First Name and Last Name as exist in the database. This CiviCRM profile is set to update the contact record, so you shouldn't have any difficulties, but using the same Email, First Name and Last Name as your database record will insure that the Drupal user and CiviCRM contact are connected.
    9. Click the Create new account button to complete the new user setup.

IMPORTANT!

Remember that you are assigning the Volunteer Coordinator role to a Drupal user/contact in your CiviCRM database. The email address must be the same. I.e., just like your Drupal user account is associated to your CiviCRM account via your email.

This shouldn't be an issue if you are setting up a new user in Drupal. Remember that you are required to enter their email address, first name and last name which automatically adds them to your database as a CiviCRM contact.

If they're already a contact in CiviCRM, then when you set them up as a Drupal user make sure you use the same email address as the primary email in their CiviCRM contact record—this way CiviCRM will update the contact record rather than create a new one.


CiviCRM Group with ACL
  1. Create a group that has access control functionality to hold the user:
    1. Go to CiviCRM → Contacts → New Group.
    2. For our purposes let's call the group Volunteer Coordinator(s).

      Even if you only want to grant/deny access to a single contact, you can only do so in CiviCRM by adding them to a group that has access control selected and ACLs built and assigned to the group.
    3. Click the Access Control checkbox.
    4. Click the Continue button.
    5. Enter the Name or Email of your user.
    6. Click the Search button.
    7. Check the checkbox for the contact.
    8. Click the Add Contacts to Volunteer Coordinator button.
    9. Click the Add to Group button.
    10. Click the Done button.

Your user/contact should now be a member of the Volunteer Coordinator(s) group. (Or whatever you've named it.)

Creating ACLs

There are three steps to creating an ACL in CiviCRM:

  1. Adding an ACL Role
  2. Assigning Users (i.e., your CiviCRM group) to the ACL Role
  3. Creating an 'ACL' and Granting Permissions

A single ACL Role can—and often will—have multiple ACLs assigned to their role. Since we (GingerFeet) took away permissions when we turned things off in Drupal, we need an ACL for each permission we want to turn back on (See Step 4 – Outline of Steps above).

Once you have created your group with Access Control functionality and added the contact(s) to the group:

CiviCRM ACL Manage Roles

  1. Add an ACL Role – this is basically giving the ACL Role a name. The role acts as a container to hold all the ACLs needed to give the group proper access.
    1. Go to Administer → Manage → Access Control.
    2. Click the Manage Roles link.
    3. Click the Add ACL Role button.
    4. Enter a name for the ACL in the Label field. Let's call this Volunteer Coordinator.
    5. Give the role a Description for future reference.
    6. Click the Save button.

On the Manage ACL Roles page, you can access the next step...

  1. Assign the Role – in this step you are telling CiviCRM that "this role" is to be used by "this group."
    1. Click the here link at the end of the text "and you can assign Roles to CiviCRM contacts who are users of your site here."

      If you return to the main Access Control page, this is 2. Assign Users to CiviCRM ACL Roles.
    2. Click the Add Role Assignment button.
    3. Select an ACL Role from the drop-down (select the Volunteer Coordinator role).
    4. Select a group from the Assigned To drop-down (select the Volunteer Coordinator group).
    5. Click the Save button.

CiviCRM ACL - Assign Users

On the Manage ACL Roles page, you can access the next step....


IMPORTANT!

You will repeat this step for each permission you need to grant. For our example above, you will repeat this step for all the items under Step 5 of Outline of Steps.


  1. Create ACL(s) and Grant Permissions
    1. Click the here link at the end of the text "You can create ACL’s and grant permission to roles here..."

      If you return to the main Access Control page, this is step 3. Manage ACLs.
      1. Click the Add ACL button.
      2. Select the appropriate Type of Data.
        1. At this point you may be saying to yourself, "Well, Vanessa, what is the 'appropriate' type of data?" Well, I'll tell ya...it has to do with what you want to grant or deny access to. For our example—and our first ACL--"Create an ACL that gives this group access to view/edit the CiviCRM Volunteer group." So....we want to select A group of contacts because that's the first thing we want to give the Volunteer Coordinator access to – the Volunteers group.
      3. Select Volunteers from the Group drop-down.
      4. Select Edit from the Operation drop-down. (Edit inherently contains the 'view' command.)
      5. Select Volunteer Coordinator from the Role drop-down.
      6. Enter a Description. (Something like "Allows VC to see Volunteer group")
      7. Click the Save button.

CiviCRM New ACL

Now we repeat this last step for allowing the Volunteer Coordinator to see the Volunteer Hours custom data.

  1. AGAIN....
    1. Click the Add ACL button.
    2. Select a set of custom data fields from the Type of Data drop-down.
    3. Select Volunteer Hours from the Custom Data drop-down.
    4. Select Edit from the Operation drop-down. (Edit inherently contains the 'view' command.)
    5. Select Volunteer Coordinator from the Role drop-down.
    6. Enter a Description. (Something like "Allows VC to edit Volunteer Hours")
    7. Click the Save button.

CiviCRM New ACL Custom Data

Repeat for allowing the Volunteer Coordinator to see the: