Item10078: Separate, enhance, and test documentation of ACL preferences

Introduction

As discussed on the #foswiki IRC (see 2010-11-25 log from 10:11 to 10:41), the Foswiki documentation, specifically AccessControl could benefit from an "outsourced" documentation of the ACL preferences. In the current version, AccessControl is just too long and contains too many aspects in too much detail. It would be nice to keep it as an overview on all access control matters but move the detailed (and improved and tested) documentation of ACL preferences to a new page (to be linked to from AccessControl.

Such a new page needs some discussion in order to determine what exactly to include and also to verify the statement made (since it is not clear that the current documentation was verified by tests).

This discussion will take place in the comments below and accepted modifications should be made in the following text.

Summary of Material and Guesses

• Tasks.Item1537
• Support.Question411
• It seems that ...TOPIC... preferences are inherited. If so, protecting a WebPreferences topic (e.g. by restricting edits to admins) means that the same protection would apply to all other topics in the web. This is probably not desired. If ...TOPIC... preferences are only effective when being defined in the current topic, then inheritance doesn't make sense...
• Which ACL preferences does Main.SitePreferences export? Asking this question on the #foswiki IRC (see 2010-11-15 log from 09:41 to 10:37) I got the answer that Main.SitePreferences does not export ACL preferences. This contradicts the statement on http://url-to-any-foswiki-1.1.2-installation/bin/view/System/AccessControl#Controlling_default_access_to_the_entire_Wiki. (yes, include the last period in the link and use a path to a Foswiki-1.1.2 installation, i.e. not foswiki.org) which says:

However, it can be desirable to default all your created webs to exclude WikiGuest by default, and then to open up only some topics, or some webs for guest users. This can be achieved by setting the DENYWEBVIEW setting (as below) in the SitePreferences topic, and then 'un-setting' it for specific Web's or topics.

• Where are ...TOPIC... preferences valid? Again, I don't fully trust the answer I got on the #foswiki IRC (see 2010-11-15 log from 10:45 to 10:47) which says that TOPIC vars apply only to the topic they're on. However, the inheritance from WebPreferences and above wouldn't make any sense then, would it?

How to Draft

Please discuss any changes to the draft in the comment section first. Also mention whether you tested your assumption.

-- AndreasKeil - 25 Nov 2010

---

Draft Area for a New Topic "AclPreferences"

Definition (What Do the 12 Preferences Macros Mean?)

The preference...	... defines a list of users/groups that are...
DENYWEBVIEW	denied viewing the web's topics.
ALLOWWEBVIEW	allowed viewing the web's topics.
DENYWEBCHANGE	denied changing the web's topics / creating topics in the web / ... .
ALLOWWEBCHANGE	allowed changing the web's topics / creating topics in the web / ... the web's topics.
DENYWEBRENAME	denied renaming the web's topics / renaming the web the web's topics.
ALLOWWEBRENAME	allowed renaming the web's topics / renaming the web the web's topics.
DENYTOPICVIEW	denied viewing the topic.
ALLOWTOPICVIEW	allowed viewing the topic.
DENYTOPICCHANGE	denied changing the content / making attachments to the topic.
ALLOWTOPICCHANGE	allowed changing the content / making attachments to the topic.
DENYTOPICRENAME	denied renaming the topic.
ALLOWTOPICRENAME	allowed renaming the topic.

Setting

There are two differences between setting the preferences inside a topic text vs. using a topic's settings (under "more topic actions"):

• Topic settings are written to the topic's meta data and therefore take precedence over preferences defined in the topic content.
• Topic settings are not visible while editing the topic.

Inheritance

• Is there any difference between ...WEB... and ...TOPIC... preferences in terms of inheritance?
• Is this inheritance path correct for both groups (...WEB... and ...TOPIC...) of ACL preferences? System.DefaultPreferences (should not be edited) -> Main.SitePreferences -> SomeWeb.WebPreferences -> SomeWeb.SubWeb.WebPreferences -> SomeWeb.SubWeb.SomeTopic If yes, then System.ManagingWebs#Subweb_preferences_are_inherited could maybe be copied/moved here.
• Explain FINAL
• Mention the usage of = * Set DENYWEBVIEW = ""
  • DENYWEBVIEW was finalised in Tasks.WebPreferences
• Set ALLOWWEBVIEW = ""
  • ALLOWWEBVIEW was finalised in Tasks.WebPreferences
• Set DENYWEBCHANGE = "%MAINWEB%.WikiGuest"
  • DENYWEBCHANGE was finalised in Tasks.WebPreferences
• Set ALLOWWEBCHANGE = ""
  • ALLOWWEBCHANGE was finalised in Tasks.WebPreferences
• Set DENYWEBRENAME = ""
  • DENYWEBRENAME was finalised in Tasks.WebPreferences
• Set ALLOWWEBRENAME = ""
  • ALLOWWEBRENAME was finalised in Tasks.WebPreferences

= and = * Set DENYTOPICVIEW = ""

• Set ALLOWTOPICVIEW = ""
• Set DENYTOPICCHANGE = ""
• Set ALLOWTOPICCHANGE = "AdminGroup"
  • ALLOWTOPICCHANGE was defined in Main.WikiGuest
• Set DENYTOPICRENAME = ""
• Set ALLOWTOPICRENAME = "%MAINWEB%.SecurityGroup"
  • ALLOWTOPICRENAME was defined in Tasks.WebPreferences

= for debugging preference inheritance

Priority

• Preferences at lower levels of the hierarchy override the ones at higher levels: user prefs > topic prefs > subweb prefs > web prefs > site prefs (or are there any differences of ACL preferences compared to other preferences?
• ...TOPIC... overrides ...WEB...
• DENY... overrides ALLOW...

Copy/move the current ALLOW/DENY precedence documenation - this seems to be quite concise.

Exceptions

Point out differences of ACL preferences compared to other preferences, if there are any. Maybe also re-iterate other exceptions, if any (like whether or not Main.SitePrefernces exports ACL preferences).

---

Discussion

Looking at the AccessControl someone sneaked in a section about how to secure the entire site by setting DENYWEB.. preferences in SitePreferences.

This entire section is wrong. The ALLOWWEB and DENYWEB preferences only work at web level. That is how they always worked from early (tm)wiki days and how they still work.

This section blurs the whole understanding of the access control. I will immediate delete this section.

It would be nice if we could define access defaults site wide but we cannot.

Restricting view script is also bad advice because in some cases it triggers double authentication or extra work load on external auth resources. We need to avoid all the geek solutions in the standard documentation and just plain and simply document how our standard features work.

-- KennethLavrsen - 25 Nov 2010

Thanks for jumping in and fixing the documentation, Kenneth! It would be very nice if we could also try to gather all the facts about ACL preferences in this Task item (because there apparently is some confusion about the exact definitionsm inheritance, and application) and then use this fact sheet for compiling a new "ACL Preferences" doc topic in the end.

-- AndreasKeil - 25 Nov 2010

OK, I just realized that the "inheritance" of the ...TOPIC... ACLs is two-fold: The variables are actually inherited from webs to topics but they are not applied as ACLs. If my understanding is correct here, it would be very helpful to make this distinction clear. Using

%SHOWPREFERENCE{"DENYTOPICVIEW,ALLOWTOPICVIEW,DENYTOPICCHANGE,ALLOWTOPICCHANGE,DENYTOPICRENAME,ALLOWTOPICRENAME"}%

in a topic is actually very confusing if one doesn't know that the variables are inherited but not in an ACL sense.

-- AndreasKeil - 30 Nov 2010

Correct. Set (and shown) variables may not work.

-- ArthurClemens - 05 Dec 2010

Looking back at this the main problem that caused the flood of questions what that our documentation had a section that was plain wrong and totally confused the picture.

What may be left to document is not urgent release blocking.

Documentation can always be better and I will review this document again. Setting this bug item Waiting For Release

-- KennethLavrsen - 06 Mar 2011

Commenting is disabled while not logged in