Section Segmentation and User Permissions Part 2 of 2

Note that this article assumes that you have administrator-like permissions in order to access the Setup tab in the Administration Interface. For information about the general layout of the Administration Interface, see this article or the eZ Publish Content Management Basics book. You should also have general knowledge on how to create and edit content in the Administration Interface.

This article was written to be compatible with eZ Publish 4.0, although the concepts and procedures should be similar for other versions.

Permission system overview

Without permissions, access to everything on a site is completely denied; it is only by the cumulative assignment of permissions that users are permitted to view content and use site functionality.

The permission system can be split into four components, as illustrated in the following figure:

Permission system components

As shown, the four components are:

• Policy: a rule granting access to a part of a site or site functionality.
• Role: a named collection of policies.
• User: a definition of a valid user account on the system. User accounts can be created via three methods: through the Administration Interface by an existing Administrator user (by default, Editor users do not have access to the User accounts tab); through self-registration on the front-end of the site; and imported from external systems.
• User group: a named collection of users. User groups can contain sub-groups.

eZ Publish comes with a set of built-in user groups, and at least an Administrator user and an Anonymous user. This ensures that there is a way to log in to perform site management tasks (and add more users and groups to the system), and that unregistered site visitors are permitted to view unrestricted content.

Similar to how a user group consists of users and possibly other groups, a role consists of policies. Roles can be assigned to user groups or individual users. Note that policies cannot be assigned directly to users or groups.

User – the content object

A content object is considered a "User" object if it contains an attribute of the "User account" datatype. All objects that have an attribute of this datatype will automatically become valid users. Here, we will explore this datatype and the built-in "User" class for an example user called "Bergfrid Skaara".

User account datatype

The "User account" datatype is critical to the permission system. You may think of it as the key property. It supports the validation, storage and retrieval of a username / password combination and an e-mail address. All elements are required. This is a datatype with several elements, similar to the "Image" datatype (although in that case, not all elements are required).

User account datatype

The Anonymous user

Recall that the permission system is cumulative, starting at a point of no access. A prerequisite for enforcing access control is that eZ Publish knows which policies to apply. This is determined by first checking the currently logged in user. But what if some unregistered random visitor is just browsing your pages? Browsing means that you can, at a minimum, view content. To address this situation, eZ Publish has a special-purpose user account, the Anonymous user (and corresponding user group).

Each time someone visits your site, they are silently logged in by eZ Publish, which sets the current user to "Anonymous". Then, the permission system can correctly apply the rules specified for this user (or group). If the visitor decides to log in with a personal account, the current user will be changed accordingly. This usually implies that the visitor is granted more rights, for example to submit comments, or to get access to the Website Toolbar (if he or she is an editor).

User class

The following screenshot shows an object of the "User" class in edit mode:

Object of the User class

The "Signature" and "Image" attributes are typically used in forums. Note that the username part of the "User account" attribute is grayed out, since it cannot be modified after the "User" object has been created.

User - the account and profile

Although the term "user account" technically references a datatype, it is more commonly interpreted by site visitors as the "ability to log in" and "personal space". The latter is usually referred to as the user profile in the front-end context, and as the My account tab in the Administration Interface. Note that "user profile" may also denote the information stored in the actual "User" object, such as first and last name, image and signature. In other words, editing your user profile means to edit the contents of the object holding your user account.

Your personal space provides access to change your password (without editing the profile), manage drafts and notifications, view orders and wish lists (if your site has a webshop), and access pending content waiting for approval (only in the Administration Interface) or a future publication date.

In order to access your personal space, you must log in to either the front-end or the Administration Interface. In the Website Interface, click the My profile link in the top right corner of the website. This opens the My profile page:

The My account tab of the Administration Interface gives access to all parts of your personal space:

My account tab

Note in particular the Current user window in the right area, where you can click links to bring up interfaces for changing information or your password. This panel is part of the overall Administration Interface layout, and is thus accessible from all tabs. In other words, you do not need to navigate to the My account tab in order to simply edit your profile or change your password.

User groups

A user group is a named collection of users and can contain both individual user objects and other user group objects. It is created, stored and managed as a content object of the “User group” class. Both users and user groups can be associated with a set of policies (called "roles") that determine privileges. You will find more information about this later. General rules are usually assigned to groups, whereas specific, dedicated responsibilities are assigned directly to individual users.

Predefined groups

The default groups are pre-configured and usually define the different kinds of users expected on your site. The default groups for sites that use the Website Interface are listed below:

Self-registered users

Self-registered users are those who have clicked the Sign up button in the Login interface or the Register link in the top right of a front-end siteaccess, and filled in and submitted the necessary user information. Such user accounts are disabled until users have clicked the link within the confirmation email sent by eZ Publish.

After clicking the confirmation link, self-registered users are activated in the Members group in sites that use the Website Interface. To gain more privileges, an advanced content manager or webmaster must move the account into another group, or assign the necessary roles to the individual account.

Managing users and user groups

The User accounts tab enables you to browse and manage nodes within the Users branch of the content node tree. This tab also provides access to the permission system so that you can view and manage roles and policies.

User accounts tab

In general, the layout of the User accounts tab follows the same principles as for the Content structure and Media library tabs. The six areas are present in their normal positions. The Search interface, main menu and path are found horizontally at the top of the page, and the left menu, main area and right area are aligned side-by-side below these elements. The left menu contains content objects belonging to the Users branch.

Managing users and user groups is done similarly to how you would manage other content objects. The same principles apply when creating, editing, viewing, copying, deleting, moving, translating and cross-publishing.

In contrast to users and user groups, roles and policies are not stored as content objects and nodes. Unlike content objects, there are no versions or translations of a role or policy. In other words, these access control components should be thought of as settings rather than content. However, do not confuse these with configuration files, which contain other types of settings. Roles and policies are stored in the database, and the only way you can work with them is through the User accounts tab.

Policies

A policy is a single rule that grants access to specific or all functionality of a module. You can set the following for each policy:

• Module: the highest level for which a policy can grant access. Examples include the "user" and "content" modules.
• Function: available functions depend on the module, and access can be granted to one or all functions of a module. If you want to give access to a subset (but not all) of the functions in a module, you have to create multiple policies, with one policy per function. Function examples include "create" and "edit" for the "content" module.
• Limitation: various levels of granularity to which the policy should apply.

Most of the modules and functions have intuitive, descriptive names, but be sure to consult your site administrator if you are unsure about what a module or function does. You can also use the Reference section in the documentation to find out more about a particular module. In most cases you will be dealing with read and edit permissions for the "content" module.

The following is a list with brief descriptions for each available limitation:

• Use the Class limitation to limit a policy to objects of certain types, such as articles or blog posts.
• Use the Language limitation to limit a policy to object versions in specific languages, such as French translations only. This only applies to multilingual sites.
• Use the Node limitation to limit a policy to a specific node. For example, you might want to enable Editor users to edit the site's frontpage, but not the contents it pulls from other areas of the site. Or, you might want to provide read access to a specific node within a restricted area.
• Use the Owner limitation to limit a policy to objects that are owned by the user who is logged in. For example, community members might be permitted to only edit their own objects (such as posts in a forum or article comments).
• Use the Parent class limitation to limit a policy based on the type of the object encapsulated by the parent node. For example, a user might be permitted to comment on blog and forum posts, but not articles.
• Use the Section limitation to limit a policy to objects that are assigned to certain sections. This is used to set up protected areas and generally keep site management off the front-end pages.
• Use the Siteaccess limitation to limit a policy to a specific site interface. For example, you might grant a group of users access to log in to the Administration Interface.
• Use the Status limitation to limit a policy to a certain version status (such as "Published" or "Archived").

• Use the Subtree limitation to limit a policy to a certain part of the content node tree. For example, a policy might allow content to be created, but only under the "Training" and "Support" nodes. This is typically used to segment editorial responsibility, and to limit areas in which public, user-contributed content is accepted.

  This limitation has some similarities to the Section limitation, but also some important differences. There might be multiple subtrees belonging to the same section, and a subtree might contain several sections.

Roles

A role is a container and grouping tool for policies. Remember that only roles, not policies, can be assigned to users and user groups. Once you have set up a role, you can re-use it and assign it as many times as necessary. Because of this you can, for example, build an access hierarchy with cumulative rights.

Managing roles

The Role list interface provides access to role management operations. To access it, click the Roles and policies link in the Access control panel in the User accounts tab.

Role list interface

Each existing role has a set of buttons that can be used to assign, copy, or edit the role. You can also remove or add roles uses the buttons at the bottom.

Click one of the role names to bring up the Role management interface for a particular role:

Role management interface

Here, you can view the policies in a role, as well as the users and groups that have been assigned that role.

Assigning a role

Role assignment means to make a connection between access rules and user accounts. After you click the Assign button, use the Browse interface to select one user or user group to which to assign the role, then click the Select button:

Browse interface -- assign role

If you want to assign a role to multiple users or user groups, you must repeat the operation, as you cannot select more than one target for the assignment at once.

You can also assign a role with Subtree or Section limitations, similar to the limitations available for individual policies. This can only be done from the Role management interface. First, select the desired limitation in the dropdown list, then click the Assign with limitation button. For Subtree limitations, this will open the Browse interface, where nodes from the content structure will be shown. For Section limitations, the page will simply reload with a special-purpose Select section window:

Select section window

Managing policies

Recall that policies cannot be assigned directly to a user or user group. You have to first add the policy to a role, and then assign the role. Because of this, there is no separate "create / delete / copy / edit / assign" functionality for policies as there is for roles. To make policy changes, you have to first edit the role that contains the policy, by clicking the edit button next to a role in the Role list interface.

To remove one or more policies from a role, mark the corresponding checkboxes, then click the Remove selected button.

Managing policies from within a role

To create a new policy in a role, follow the steps below.

1. Click the New policy button when editing a role. This will open the Policy wizard:

Policy wizard introduction

2. The wizard contains three steps with instructions to help you create a new policy. Select a module, such as "content", from the dropdown list. Then, grant access to all or just one function of that module by clicking the corresponding button. If you click the Grant access to all functions button, the policy will be added to the role and the procedure is complete. If you click the Grant access to one function button, the wizard continues to step two. (Note that the numbering of steps in the wizard does not correspond to the numbering of steps in this procedure.)

3. Select a function, such as "translate", from the dropdown list.

Policy wizard -- select module and function

Grant full or limited access to the function by clicking the corresponding button. Some functions do not support limitations, such as when you grant access to use notifications. If this is the case, or if you grant full access to the function, the policy will be added to the role for the given module and function (and the procedure is complete).

If you selected to grant limited acc4. ess to the function, continue with step three of the wizard, where you select the function limitations.

Set the desired function limitations using the appropriate controls. For example, you could limit the policy to apply to articles within the Standard sections in English and Norwegian (excluding French and German).

Policy wizard -- specify limitations

The function limitations vary, depending on the module and function previously selected. Keep in mind that limitations are applied together, making the resulting function limitation more permissive for each limitation you select within the policy.

5. Click the OK button to finish the wizard. The policy will be added to the role that is currently being edited.

In this example, we will combine what you learned about sections in the first article in this series with the access control concepts from this article to create a protected area of the site. Note that you can do much more with user permissions than grant or limit access based on sections – be sure to explore the possibilities on your own!

Recall that by default, the Content structure tab is associated with the Content top-level node and the Standard section. The out-of-the-box eZ Publish
behavior is that everything published here constitutes a visible part of your site. This means that everybody, both logged in and anonymous users, is able to view all content located here. For example, if you create a new article in the Content structure tab, it will be visible to everybody.

A "protected area" is a part of your site that is only accessible to a certain group of users. For example, a company might have some employee-only material or annual reports available only to trusted clients.

In short, to make a protected area, you must segment the node tree by creating a new section and assigning it to some node(s). Then, you must use the permission system to grant access to the secret section for a specific group of users. The procedure below goes through the specific steps to create an example protected area:

1. Access the Administration Interface and navigate to the Content structure tab.
2. Create a folder called "Secret documents" somewhere under the Content top-level node. You can verify that it is in fact displayed on your public site at this time.
3. Bring up the Sections interface by navigating to the Setup tab and clicking the Sections link on the left menu.
4. Create a new section called "Secret section" by clicking the New section button and providing the name and navigation part.

5. Assign the newly created section to the "Secret documents" folder that you created in step 2. To do so, click the Assign button to the right of your new section in the Sections interface. Browse to the correct folder, mark its radio button, then click the Select button.

   You can now verify that the "Secret documents" folder is inaccessible from the public front-end site by bringing up your site in another browser window and attempting to access the folder.

6. In the Administration Interface, navigate to the User accounts tab and create a new user group called "Secret users".
7. Create a new user within the "Secret users" group.
8. Create a new role called "Secret role". To do so, click the Roles and policies link in the Access control panel in the User accounts tab. Then, click the New role button and name the role.

9. Add a new policy to the role as described on the previous page.

   Grant access to the "read" function in the "content" module. During the final step where you add limitations, make sure that the policy grants access to the "Secret section" section.

10. Assign both the Anonymous role and the newly created role to the "Secret users" group as described on the previous page.

Bring up your site and attempt to log in with the user that was created inside the "Secret users" group. The user should be able to access the "Secret documents" part of the site, while anonymous users will still be blocked.