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:

  1. in the admin web interface at http://yoursite/admin/acl/rules
  2. 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:

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 files
  • openoffice for Open Office files
  • embed for media imported with mod_oembed and mod_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.