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

pencil
Priority: Normal
Current State: Closed
Released In: 1.1.3
Target Release: patch
Applies To: Engine
Component: Documentation
Branches:
Reported By: AndreasKeil
Waiting For:
Last Change By: KennethLavrsen

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 question changing the web's topics / creating topics in the web / ... question.
ALLOWWEBCHANGE allowed question changing the web's topics / creating topics in the web / ... question the web's topics.
DENYWEBRENAME denied question renaming the web's topics / renaming the web question the web's topics.
ALLOWWEBRENAME allowed question renaming the web's topics / renaming the web question 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

  • question Is there any difference between ...WEB... and ...TOPIC... preferences in terms of inheritance?
  • question 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
 

ItemTemplate edit

Summary Separate, enhance, and test documentation of ACL preferences
ReportedBy AndreasKeil
Codebase 1.1.2
SVN Range
AppliesTo Engine
Component Documentation
Priority Normal
CurrentState Closed
WaitingFor
Checkins distro:9de31b45f95a distro:8e9e426553e9 distro:9431e8de512c distro:b6d04762998b
TargetRelease patch
ReleasedIn 1.1.3
Topic revision: r14 - 16 Apr 2011, KennethLavrsen
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy