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
)msoffice
for Microsoft Office filesopenoffice
for Open Office filesembed
for media imported withmod_oembed
andmod_video_embed
none
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 an user group is not allowed to upload any files then enter none
.
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_schema/2
function, add an
acl_rules
section under the data
property in the #datamodel{}
record:
%% yoursite.erl
-module(yoursite).
-mod_schema(1).
-export([
manage_schema/2
]).
%% .... more code here...
manage_schema(install, Context) ->
#datamodel{
%% your resources...
data = [
{acl_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}
]
}
]
]
}.
manage_schema({upgrade, 2}, Context) ->
%% code to upgrade from 1 to 2
ok;
Compile the code and restart your module to load the managed rules. They will be added and immediately published.
The set of rules defined in manage_schema/2
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.