mod_acl_user_groups
This module adds rule-based access control.
- All resources (pages) are put into a content group.
- All users are member of zero or more user groups.
- Content groups are arranged in a hierarchy.
- User groups are arranged in a hierarchy.
ACL rules are defined between user groups and content groups. Each single rule gives some user group one or more permissions on some content group.
Managing user groups
By default, Zotonic has four user groups:
- anonymous (anonymous visitors of the website)
- members (logged in users of the website)
- editors (content editors)
- managers (manage users)
These user groups are arranged in a hierarchy, so that each group has the permissions its parent plus more. So, the permissions of users in the members group include those of anonymous users; and editors have the permissions of both anonymous users and members plus more.
To add or remove user groups, go to Auth > User groups in the admin.
Collaboration groups
Collaboration groups are a special type of user groups. They are most useful when you have groups of users that together collaborate on content. All content belongs to the group. Each collaboration group has one or more managers. So if you have groups of students working together and being supervised by teachers, you can define them as collaboration groups with the teachers as managers.
Managing content groups
By default, Zotonic has two content groups:
- default (all site content)
- system content (categories, predicates and user groups)
To add or remove content groups, go to Structure > Content groups in the admin. Just like user groups, content groups are ordered in a hierarchy. So the permissions that apply to the parent content group also apply to all of its children.
Defining access rules
You can add ACL rules in two ways:
- in the admin web interface at
http://yoursite/admin/acl/rules - in your site’s or module’s code; see Managed rules below.
Let’s start by defining rules in the web interface.
Content access rules
Each content access control rule grants some user group one or more permissions on some content group. So, for each rule you must specify the following properties:
- User group
- Content group
- Resource category (or ‘all categories’)
- Permissions: ‘view’, ‘insert’, ‘update’, ‘delete’, ‘link’, ‘manage own’.
If you wish to narrow down the rule, you can select a single resource category it applies to. The default is ‘all categories’.
The content group dropdown contains:
- all your Managing content groups
- all your Collaboration groups
The permissions include simple resource permissions that determine whether users in the group are allowed to view, insert, update or delete resources. The ‘link’ permission is about creating outgoing edges from resources in the content group to other resources.
Some rules may be greyed out and have a note saying ‘This rule is managed by module …’. These are Managed rules that you cannot edit in the web interface.
Collaboration group rules
Collaboration rules are special content access rules that apply to content in collaboration groups only. Each rule applies to all collaboration groups.
Allowed media
For each user group it is possible to define:
- Maximum size of uploaded files
- Allowed types of files
In the admin, go to Auth > Access control rules > File Uploads tab to edit them.
The file size and allowed types is inherited along the user-group hierarchy. For example, if Managers is a specialized subgroup of Editors then all settings of Editors also apply to all Managers. Not the other way round.
The file types are entered using the mime type or extension of the allowed files.
The following are allowed types:
- Any mime type (e.g.
image/png) - Wildcard mime type (e.g.
image/*or*/*) - A file extension (e.g.
.txt) msofficefor Microsoft Office filesopenofficefor Open Office filesembedfor media imported withmod_oembedandmod_video_embednone
The default is: image/*, video/*, audio/*, embed, .pdf, .txt, msoffice, openoffice
The default mime types can be changed with the site.acl_mime_allowed key.
The default upload size is 50MB.
If a user group is not allowed to upload any files then enter none.
Access control on properties
Some private sensitive resource properties are protected by the ACL rules. The privacy property defines who can see these properties.
The default privacy for category person is collaboration group members. For other categories the default is public.
The privacy property can have the following values:
- 0 public
- 10 members
- 20 member of same user group (except default members group)
- 30 collaboration group members
- 40 collaboration group managers
- 50 private
Increments are 10 so that more refined options can be added by custom modules.
The protected properties are:
- phone
- phone_mobile
- phone_alt
- address_street_1
- address_street_2
- address_postcode
- address_city
- date_start
- date_end
- location_lat
- location_lng
- pivot_location_lat
- pivot_location_lng
- pivot_geocode
- pivot_geocode_qhash
Module access rules
Each module access rule grants some user group use permissions on some module. In the admin, go to Auth > Access control rules > Modules tab to edit them.
Deny rules
By default, rules grant some permissions. But sometimes you want to deny some permissions that are granted by another rule. For instance, if you have a rule that allows anonymous users to view all content groups, but you have a special content group ‘Top secret’ that you want to hide from anonymous users, add a rule to deny access:
| Deny | ACL user group | Content group | Category | Permissions |
|---|---|---|---|---|
| √ | Anonymous | Top secret | All | √ View |
Publishing rules
When you’re editing rules, they are not effective immediately: you have to publish them first. Click the ‘Publish’ button to do so.
You can test out your rules before publishing them by clicking the ‘Try rules…’ button.
Managed rules
Above you’ve seen how you can add rules through the web interface. Using module versioning, you can also write rules in your code. These rules are called ‘managed rules’ because they are defined in the code of modules, including your own site module.
While editing a simple set of ACL rules in the web interface is easier for end users, developers may prefer to manage more complex rules in code. Managed rules have two important advantages:
- they are equal between all environments (such as development, acceptance and production)
- when developing and deploying new features, ACL rules and code often belong together. By defining the rules in your code, you can commit and store them along with the feature code.
If you haven’t yet done so, set up
module versioning in yoursite.erl or
mod_your_module.erl. Then, in the manage_data/2 function, call the
m_acl_rule:replace_managed/3 function to add your new ACL rules.
Note that you always to need a manage_schema/2 function, even if it only
returns ok. Otherwise the manage_data/2 function will not be called:
%% yoursite.erl
-module(yoursite).
-mod_title("Your Site").
-mod_description("An example module for the docs").
-mod_depends([ mod_acl_user_groups ]).
-mod_schema(1).
-export([
manage_schema/2,
manage_data/2
]).
%% .... more code here...
manage_schema(install, Context) ->
#datamodel{
%% your resources...
};
manage_schema({upgrade, 2}, Context) ->
%% code to upgrade from version 1 to 2
ok.
manage_data(install, Context) ->
Rules = [
%% A resource ACL rule is defined as {rsc, Properties}
{rsc, [
{acl_user_group_id, acl_user_group_members},
{actions, [view, link]},
{is_owner, true},
{category_id, person}
]},
%% A module rule is defined as {module, Properties}
{module, [
{acl_user_group_id, acl_user_group_editors},
{actions, [use]},
{module, mod_ginger_base}
]},
%% A collaboration group rule is defined as {collab, Properties}
{collab, [
{is_owner, true},
{actions, [view, insert, update, link]},
{category_id, text}
]}
],
m_acl_rule:replace_managed(Rules, ?MODULE, Context);
manage_data(_Upgrade, Context) ->
ok.
Compile the code and restart your module to load the managed rules. They will be added and immediately published.
The set of rules added with m_acl:replace_managed/3 is declarative and complete.
That is to say, you declare the full set of rules that you wish to define. Any
changes or deletions that you make to the rules in your code, will propagate to
the site’s rules. To protect the set’s completeness, managed rules cannot be
altered in the web interface.
Exporting and importing rules
To back up your rules, go to Auth > Access control rules and click the ‘Export edit rules’ button. The backup will include the full hierarchies of all user and content groups.
You can import a previous backup by clicking the ‘Import edit rules…’ button.