OpenWGA 7.11 - OpenWGA Concepts and Features

Authorisation

Document level authorisations

This chapter describes authorisation settings that are chosen for individual documents. Setting these authorisations may influence other documents as well that are related to the modified document.

Document level authorisation builds upon application level authorisation in that it may further restrict the authorisations granted there. Document level authorisation however cannot extend authorisation beyond what is decided on application level. So for example it is impossible to give any user writing access that is at access level "Reader".

Document level authorisations are set in the form of metadata fields with special, security related purpose. Authorisation fields are mostly multivalue and may contain multiple names of users or groups from the applications authorisation source or roles defined on the applications ACL. The users contained in the authorisation field will be granted the restricted feature that the individual metadata field controls. An empty authorisation field - unless explicitly documented otherwise - means that the feature is not restricted, at least not beyond what is already configured on Application level authorisation.

Authorisation related metadata fields are also documented with document types. The metadata field table shows a flag "Authorisation" next to those fields.

Authorisation fields on schema documents

The metadata field "editors", available on both language definition and content type documents, specifies users who will be allowed to edit, modify or delete struct entries and content documents that belong to the given content type or language. An empty "editors" field allows everyone with sufficient access level/privileges to modify the data of the respective type.

In OpenWGA content manager this field is available as field "Authorisation" on the editor for these document types, for example on a content type of name "document":

screenshot_09.bmp


Authorisation fields on data documents

For website areas

There are two authorisation fields on website area documents that influence access to the contained pages:

  • The metadata field "readers" contains users that are allowed to generally access content data inside the website area page, including read and write access. An empty readers field means that anyone can access the area, but once the readers fields is filled all users that are not contained in it - either directly by username or indirectly as group or role - will not be able to see its content data. For these users OpenWGA will behave like the content data of this area does not exist. This right may be further restricted by the pages in the page hierarchy.

  • The metadata field "editors" specifies users who generally are allowed to create, edit and delete struct entries content content documents in the given area. This right may be further restricted or loosened by other pages in the page hierarchy.

For a detailed explanation of the role of these fields in hierarchical authorisations see Using hierarchical authorisations.

When one of this field is empty it allows the respective right to everyone generally owning this right on application level.

Editing rights cannot be effectively issued to people that are excluded an areas readers field.

Both fields are available in OpenWGA content manager on the editor for website areas:

screenshot_10.bmp

For pages and page hierarchies

The authorisation fields that control access for a page are stored internally on the struct entry document.  Three security related metadata fields are available here:

  • The metadata field "readers", titled in content manager "Who may read this page and subpages", contains users, groups and roles that are allowed to access the content data of the page generally, including read and write access. An empty readers field means that anyone can access the page, but once the readers fields is filled all users that are not contained in it - either directly by username or indirectly as group or role - will not be able to see the content data. For these users OpenWGA will behave like this content data does not exist.

    The reading restriction is effective for:
    • All content documents on the page that has the restriction set
    • All content documents of the page hierarchy below that page. This includes child pages that have their own read restrictions. Read restrictions can only be reduced down the hierarchy, never loosened.
  • The field "childeditors", titled in content manager "Who may create childpages",contains users, groups and roles that are allowed to create, modify and delete struct entries and content documents that are in the hierarchy below the current struct entry. When the fields is empty then it inherits this setting of its parent document, either from the field "childeditors" of a parent page or the field "editors" of its area if it is a page at root. That way a setting on a special struct entry can be inherited down the hierarchy until it is redefined on some special lower struct entry.

  • The field "pageeditors", titled in content manager "Who may edit this page" contains users, groups and roles that are allowed to create, modify and delete the current struct entry and its content documents. When the field is empty it also inherits the setting from the parent pages "childeditors" field or the "editors" field of its area if it is a struct entry at root.

For a detailed explanation of the usage of those hierarchical authorisation fields see Using hierarchical authorisations.

Editing rights cannot be effectively issued to people that are excluded by a readers field of any page up the page hierarchy or the area.

In OpenWGA Content Manager all three fields are available in the page properties editor (Button page-properties.png on the left explorer panel): The field "readers" as "Who may read this page and subpages", the field "childeditors" as "Who may create childpages" and "pageeditors" as "Who may edit this page":

screenshot at 2013-04-19 15:26:47.png

The editors for each field are enhanced, so that an author may choose predefined settings from a list box while the content manager application fills the fields with the right contents for each setting. For example: Choosing "inherited" from the list box will automatically store the respective field with empty content. Choosing "only defined users" will show a detail field where those user/group/role names that are allowed can be specified.

Editing rights special features

When the fields for editing rights are not empty they normally completely redefine those rights. This may be a reduction or an extension to those rights inherited from parent documents. A special string "#inherit-and-reduce" can be used as first entry of these fields to also let them reduce the rights inherited from the parent document (just like the "reader" fields works). Documents whose editing field features this first entry will only be editable for users who are included in the field "childeditors/editors" from the parent document AND in the further entries of the current documents field.

Imagine a parent page having the following entries in field "childeditors":

  • accesslevel.manager
  • #maintenance

This reduces the editing rights to all parent pages to people either being of access level "Manager" (see Virtual user groups) or having the role "#maintenance".

A child page may have the following entries in its field "pageeditors":

  • #inherit-and-reduce
  • Administrators

The special first entry "#inherit-and-reduce" triggers the reducing behaviour. To edit this child page both fields, the one of the parent and the one of the child, need to allow you to. You need to be either manager or have role "#maintenance" AND you need to be in the group "Administrators".

This usage mode is especially applicable for data-driven applications like those of the HDBModel framework, as here it is typical to further restrict access down the hierarchy.

For individual content documents

The content document features the following authorisation fields:

  • The content document also owns a metadata field "readers" that contains users, groups and roles that are allowed to access the content document generally, including read and write access. This field is regarded obsolete since the reader field on the page is available and is not modifiable by content authors, unless the application is configured to use them. An empty readers field - as is default - allows everyone read access unless restricted otherwise.

  • The fields "author", "owner" and "coauthors" all three contain users, groups and roles that are granted "authoring rights" on the content document. Authoring rights are only effective for users of access level "Author", who generally are able to edit content documents but only those that they have authoring rights on. If an "Author" level user is not contained in any author field he may not edit the document.  The three fields have the following separate purposes:
    • The readonly metadata field "author" contains the user that created the current version of the content document. 
    • The metadata field "owner" originally contains the user that created the first version of the content document and is inherited to further versions. Its content may be changed to transfer ownership to another author.
    • The metadata field "coauthors" contains users, groups and roles who should also have authoring rights on the content document. In that case an empty field does NOT allow anyone authoring rights but instead allows no additional authors beside "author" and "owner".

Those latter three fields are available in OpenWGA Content Manager for every single content version in the content properties editor, section "content properties". The "author" field however may not be modified:

screenshot_15.bmp

Using hierarchical authorisations

The fields pagereaders, pageeditors and childeditors can be used to effectively set authorisations for complete page branches and determine rights in a way that is inherited hierarchically. This chapter outlines the exact way these fields work and shows usage scenarios.

Page readers

The pagereaders field, titled with "Who may read this page and subpages" in Content Manager, reduces the visibility of pages of a branch to the users, groups and roles contained in the field. This includes the visibility of all content documents on this page and subpages in any state.

When the field is empty then the readers settings of the parent document are inherited, this being the "pagereaders" field of a parent page or - when on a root page - the "readers" field of the website area.

Page reader fields reduce visibility in an "additive" way down the hierarchy. This means that visibility restrictions determined for one struct entry add up to the restrictions already determined on some parent entry up the hierarchy. Or said another way: A page is visible to a user when its readers field allows read access (so is either empty or contains an entry of one of his user names, groups or roles) and also do the reader fields on all parent entries up the hierarchy, independently from each other.

It is impossible to loosen visibility constraints "down the hierarchy". When a page is invisible for some user then also all of its child pages are.

WGAPI-wise page readers visibility is not enforced for the struct entry part of the page, only for the content. Content Manager however does not display pages that are invisible, also WebTML navigators will not as they only work on content documents.

An example

See the following example hierarchy:

screenshot at 2012-11-27 12:39:36.png

The website area in this example reduces visibility to the group "staff-members", meaning that all content inside this area will only be visible to members of this group (although not all of this content necessarily is visible to all members).

Documents "Home" and "News" have readers field empty, so they inherit their visibility from the area.

Document "Accounting Information" reduces visibility to two groups: "Accounting-members" and "Management". But as we said, reader fields work additive in hierarchy, so this means that the restrictions of the area are still in effect here. To now effectively express in a concise boolean rule what people are able to see this document we may follow these rules:

  • All entries in one readers field are connected via "OR" to a reader field rule
  • The rules of the reader field from the page (if filled) and all pages up the hierarchy are enclosed by brackets and by connected via "AND" to a complete visibility rule

Regarding document "Accounting information" this means users owning the following users/groups/roles can see the page and its content:

("Staff-members") AND ("Accouting-Members" OR "Management")

Document "Management" further reduces the visibility of itself to group "Management". So the rule for this document is:

("Staff-members") AND ("Accouting-Members" OR "Management") AND ("Management")

Effectively this annihilates the "Accounting-Members" group authorisation, determined by the parent page, for this page. So this could be shortened to the effective rule:

("Staff-members") AND ("Management")

Usage scenarios

The hierarchical page readers functionality is designed to be a secure and dependable way to reduce accessibility to certain ranges of content. Because of this there is no way to modify the reader settings done on some page for any subpage.

While it may be difficult to explain the exact impact of certain hierarchical reader field scenarios the results that emerge from the way these fields work is mostly what is expected and practical. The page hierarchy in OpenWGA Content Stores normally is organized in a way that represents the problem/responsibility domains of the stored data. When this is given then the readers field of each page can simply include the users, groups and roles of the people of that individual domain, so their content remains visible only to them.

As page branches deeper down the page hierarchy normally should represent even smaller sub-domains of their parent pages the readers fields additive nature is ideal to further reduce the visibility of these pages to the smaller group of people responsible here.

Page and child page editors

The pageeditors fieldtitled with "Who may edit this page" and the childeditors field, titles with "Who may create childpages" in Content Manager, reduce the rights to edit pages of a branch to the users, groups and roles contained in the field. 

When any of both fields is empty then the settings of the parent document is inherited by it, this being the "childeditors" field of a parent page or - when on a root page - the "editors" field of the website area.

When editor fields are filled they normally completely determine editing rights for that page and make all settings of parent documents ineffective for it.  A person has the right to edit a page when:

  • Either the "pageeditors" field of that page contains names which explicitly allows it
  • Or the "pageeditors" field of that page is empty and:
    • Tthe "nearest" filled "childeditors" field on the parents up the hierarchy explicitly allows it
    • There are no filled "childeditors" fields up the hierarchy and the "editors" field on the area explicitly allows it or is empty

By editing a page is meant: Edit the page and its properties and also edit any content document on it.

The "childeditors" field also controls the right to create subpages for a specific page. A person has to right to creae a page when:

  • Either the "childeditors" field of the parent page contains names which explicitly allows it
  • Or the "childeditors" field of that page is empty and:
    • Tthe "nearest" filled "childeditors" field on the parents up the hierarchy explicitly allows it
    • There are no filled "childeditors" fields up the hierarchy and the "editors" field on the area explicitly allows it or is empty

This way of work allows the combination of "childeditors" and "pageeditors" field in a hierarchy to either reduce or extend editing rights down the hierarchy. This differs from "pagereaders" which always works additive and can only reduce rights down the hierarchy.

An Example

screenshot at 2013-04-19 15:54:03.png


Here we show the editor fields of the example page hierarchy. The website areas "editors" field allows only "Chief-Editors" to edit the base structure of the website, including documents "Home", "News", "Accounting Information", "Communities", "Downloads" and "Sitemap". This is to protect this structure which hardly ever changes from being accidental corruption.

On some of those subpages you see that that the "childeditors" field is modified to effectively give the responsibility of that page branch to another group. Group "News-staff" may create and edit pages below "News" (but not page "News" itself), group "Moderators" may do the same below "Communities" and group "Uploaders" below page "Downloads".

On some specific pages the "pageeditors" field is modified to allow certain groups editing of this very document, but not allow them to create or modify any subpages. Document "Management" may be edited by group "Management", also document "Markering" by group "Marketing" but both cannot create new pages below those respective pages or could edit existing ones.

Note that every set child/page editors field here also removes editing rights for "Chief-editors", because they are no more included. To keep rights for this group it should be added to each field as additional group.

Usage scenarios

On most occasions a website may want to protect its basic structure from illegitimate corruption, so mostly the editing rights on the highest document levels are the most restrictive. This can be accomplished by specifying those rights right on the area. 

On lower page levels the editor fields can be used to loosen or delegate editing rights to certain responsible groups, either for a subpage branch via "childeditors" or for a single page via "pageeditors". However what should be protected how much always depends on what the website shows. Editing rights may need to be extended or reduced down the hierarchy which is both possible with these editor fields.