This document provides an overview of the theory behind user permissions/access levels within the Checkbox application.
- User Roles
- User Permission Settings
- Access Control Lists (ACL)
- Permissions Diagram
- User Permissions Review
NOTE: Throughout this guide, the shorthand ‘entity’ will be used when discussing any of the following access-controllable Checkbox functions:
- User Groups
- Email Lists
User roles are assigned to Checkbox users upon creation and dictate which Checkbox entities (surveys, users, libraries, reports, etc.) a user has the ability to access. You can select one or more user role(s) for any given user, depending on the level of access you wish to grant them within Checkbox.
The following is a list of all user roles and the actions each role is capable of:
- System Administrator: Has the most access to an account. Can change the settings of the application and view/edit/respond to all entities within Checkbox.
- User Administrator: Has the ability to create and modify new users. User Administrators can only modify users they have created.
- Survey Administrator: Has the ability to create, modify, and activate new surveys and libraries. Survey Administrators can also create and modify Styles.
- Respondent: Has the ability to respond to surveys.
- Report Viewer: Has the ability to view existing reports (when granted access by the report creator or a System Administrator).
- Report Administrator: Has the ability to create and modify new reports.
- Survey Editor: Has the ability to modify existing surveys (when granted access by the survey’s creator or a System Administrator).
- Group Administrator: Has the ability to assign users to groups.
The appropriate user role designation is required in order for a user to complete entity-specific actions within Checkbox. For example, if a particular user has been assigned the Report Viewer role and that user wishes to edit the report, they would not be able to. Their user role designation permits the user to view reports only. In order for that user to be able to edit a report, they would first need to be assigned the Report Administrator role by a System or User Administrator.
However, the user role alone does not give a user access to an entity. By default, a user has access to only the entities they have created, be that a survey, a report, a user group, etc. If you would like to grant a user access to an entity they did not create, the user will need to have the correct user role(s) and have been added to the entity’s Permission settings.
In the above Report Administrator example, being assigned the Report Administrator role is only to step one of having administrative access to an existing report. That user must also be added to the report’s permission settings by the creator of the report or a System Administrator.
User Permission Settings
Permissions, also referred to within Checkbox as Security, control which access-controllable entities a user (with the correct user role) can create, modify, or view.
Permissions can be set on:
- User Groups
- Email Lists
Within the permission settings of each access-controllable entity is an Access Control List (ACL), where users can be granted/denied permission to access the Checkbox entity.
Access Control Lists (ACL)
Many entities in Checkbox have an Access Control List (ACL). The ACL is where user permissions are controlled for a Checkbox entity.
Keep in mind that an entity can be a subset of a broader entity. For example, a report is part of a survey, which could be part of a folder. A user cannot be given access to the report without first being added to the ACLs of both the survey and the folder the survey resides in.
Users may only be added to a particular entity’s ACL if their individual user role(s) correspond to that entity. For example, Survey Editors and Survey Administrators can be added to the ACL of a survey or folder, but not a user group.
NOTE: System Administrators are permitted to access all entities within Checkbox, therefore they are included on all ACLs by default and their permissions cannot be modified (see image above).
A user must first be added to an ACL before their access permissions can be configured. To add a user to an ACL select Permissions from the entity’s Actions Menu or Settings Menu (examples above from top to bottom: Report Actions Menu, Survey Settings Menu, Folder Settings Menu).
When the ACL window appears, move to the Add Users/Groups to Access List tab.
Users/groups on the right are already included on the ACL (System Administrators will appear on the right by default because they have access to all entities within Checkbox).
Users/groups on the left can be added to the ACL by clicking the desired entry. The entry will then move to the right-hand box.
The next step is to configure the newly added user’s permissions. To do this, move to the Access List tab.
Select the newly added user to reveal a list of permissions on the right. Select desired permission(s), making sure that the permission level you select corresponds with the user’s designated user role(s). In the example above, the newly added user happens to be a Survey Editor, therefore the only permissions available to the user are the “Take Survey” “and “Edit/Take Survey” options. If the user was a Survey Administrator, however, we would also be able to select “Administer Survey” and “Analyze Data” and “View Survey Responses” from the permissions list.
NOTE: Available permissions vary depending on the Checkbox entity. The above example illustrates the permission options for a survey.
After configuring the user’s permission level, select Save Changes.
A survey’s Default Policy is the permissions setting for all users not included on the entity’s ACL. For example, if on the Access List tab you granted specific users permission to administer a survey, but want anyone not specified on the ACL to still be able to respond to the survey, set the Default Policy to “Take Survey” (see image above). ACL permissions supersede any default policy.
User role limitations still apply for default policy permissions. For example, if the default policy for a survey is “Edit/Take Survey”, only users with the Survey Editor or Survey Administrator user role are able to access the survey.
NOTE: There are two exceptions to this rule, which allow anonymous persons not registered in Checkbox as users (no assigned user role) to access specific entities. The first is setting the default policy of a survey to “Take Survey”, which allows anyone with the survey URL to take the survey without the Respondent user role. The second is setting the default policy of a report to “View Report”, which gives anyone with the report URL the ability to view the report without the Report Viewer user role. The reason for the two exceptions is because both of these actions technically act outside of the application.
The above flow chart illustrates the process Checkbox uses to evaluate permissions.
From the diagram, the following key points about access control become clear:
- An ACL policy cannot grant permission to a user who is not in a role that also grants the corresponding permission. For example, users with a Respondent role only can only be added to the ACL of surveys and folders.
- An ACL policy can deny permission to a user even if they have the correct role designation. For example, a user with a Report Viewer role must either be included on the report’s ACL, or the report has a Default Policy which permits non-ACL access.
- An ACL policy for a user or group can deny permission to that user or group even if the default policy grants that permission to every other user
User Permissions Review
- Checkbox allows you to set permissions on Surveys, Folders, Reports, User Groups, Libraries and Email Lists.
- Checkbox allows you to set different access roles for individual users within Checkbox.
- Being assigned a user role does not in of itself grant a user access to a Checkbox entity. Being a member of a role simply controls which permission can be granted to a given user.
- The System Administrator has rights over all entities of Checkbox and does not need to be configured on any ACL or security page. When testing surveys for your respondents DO NOT use the System Administrator account since permissions will be superseded and you will not have a proper representation of how your survey will behave.
- If you configure the permissions of your survey correctly but a user still cannot view/edit it, be sure to double check your folder permissions to confirm you have set those permissions as well.