Module name TWiki::Access AccessDotPm Location TWIKIROOT/lib/TWiki/Access.pm Summary To provide access checking Primary Author PeterThoeny CVS history CVS:lib/TWiki/Access.pm CVS alpha CVSget:lib/TWiki/Access.pm Contributing authors (see CVS History) Is Class NO First Release to be filled out

File Hierarchy   TWIKIROOT   lib   TWiki   Access.pm

Purpose

• To provide methods for the CgiScripts to check whether a user is permitted to change something.
• NB Plugins should use the equivalent interface in FuncDotPm
• provides an API to access the information in TWikiGroups - though the Name of the topic seems to be configurable too

Used by

This module is primarily used by the CgiScripts

Important parameters

Please see CodevDocumentationProject and CodevDocumentationProjectDev for comments on the format of these pages.

Dynamic access control and permission caching

As TWiki:Codev/DynamicAccessControl suggests, various cool things can be done if TWiki variables in access control variables such as ALLOWTOPICVIEW and ALLOWWEBVIEW are expanded before examining whether the user is in those values. Now we have the feature. This chapter describes its design details.

If that's implemented naively, permission checking may take significantly longer than before in some cases. So having efficiency in mind is crucial.

There had been room for efficiency improvement in access control. So this is a good opportunity to improve efficiency in general of access control.

Basics of dynamic access control

If an access control variable contains % and %DYNAMIC_ACCESS_CONTROL% is on at the web level, the access control variable is evaluated by TWiki::handleCommonTags(). And then, permission is determined.

During variable expansion, access checking may occur. For example, %FORMFIELD{"fieldname"}% causes access checking. To prevent infinite recursion, a TWiki::Access class instance now has recursion attribute housing recursion depth. If checkAccessPermission() ends up calling itself, the recursive call returns true immediately.

When to check the user is an admin

Most topics doesn't restrict viewing. While checking admin membership takes some cost. Checking if the user is an admin should take place immediately before concluding permission is denied.

$users->isAdmin($user, $topic, $web) depends on the user mapping handler. Under TWikiUserMapping, a user is an admin or not regardless of web or topic. In that case, once a user is determined to be an admin, subsequent calls to TWiki::Access:checkAccessPermission() can return true without looking into access control variables such as DENYTOPICVIEW or ALLOWWEBVIEW.

This may not be true under other user mappings. Each web may have its own admin.

$TWiki::cfg{Access}{AdminDomain} is to specify the span. It's either "site" (default) or "web".

It is thinkable that admin differs from topic to topic within a web. But that seems chaotic and until a realistic scenario of that is presented, that is not considered.

Why caching matters

In general, during a single session (the lifetime of a TWiki class instance), TWiki::Access::checkAccessPermission() is called multiple times. In some cases quite a fiew times - for example, %SEARCH{...}% checks view permission for all topics it processes. As such access permission checking should be efficient.

Most topics don't have DENYTOPIC* or ALLOWTOPIC* set. In that case, DENYWEB* and ALLOWWEB* determins permission, which is the same for all topics in a web. This provide an opportunity for caching to increase efficiency.

The same topic may be INCLUDEd multiple times in a topic. In that case, caching a topic's permission contributes to efficiency.

Admin membership is another factor. Once a user is determined to be an admin, you can skip accecc checking and simply return true.

Determining wheter the user is a member of an access control variable value may take time if groups are involved. So it's thinkable to cache whether the user is in a string or not. But until a good number of cases where membership caching is useful, it's not implemented.

How permission should be cached and cached data should be used

Only view permmission and admin membership are worth caching. There are no ways for change or rename permission to be checked more than once in a session let alone root permission.

If the user is turned out be an admin, that fact must be recorded to save the effort of determining permission subsequently.

In checkAccessPermission() cached permission data is used as follows:

1. , cached admin membership
2. cached topic level access
3. (actual topic level permission check)
4. cached web level access
5. (acttual web level permission check)

When examined, access to the topic needs to be cached because regardless of access control variables, whether it's determined statically or dynamically, access to the same topic remains the same and there are cases where access to the same topic is examined more than once.

In addition, access at the web level can be cached in some cases.

Data structure

A TWiki::Access class instance now has cache attribute for permission caching, which has a slot for each user.

Notes for unit test

Once checkAccessPermission() returns a value for a user-web-topic combination, the same value is always returned for the same user-web-topic combination during the same session.

UnitTestContrib functions may call checkAccessPermission() repeatedly for the same user-web-topic combination while changing other arguments. As such, in test functions, before calling checkAccessPermission(), the session's permission cache needs to be cleared.

package TWiki::Access::Helper

A class for permission caching. Its instance is constructed at the beginning of checkAccessPermission().

package TWiki::Access

A singleton object of this class manages the access control database.

ClassMethod new($session)

Constructor.

=begin twiki

ObjectMethod finish()

ObjectMethod getReason() -> $string

Return a string describing the reason why the last access control failure occurred.

ObjectMethod checkAccessPermission( $action, $user, $text, $meta, $topic, $web ) -> $boolean

Check if user is allowed to access topic

• $action - 'VIEW', 'CHANGE', 'CREATE', etc.
• $user - User id (not wikiname)
• $text - If undef or '': Read '$theWebName.$theTopicName' to check permissions
• $meta - If undef, but $text is defined, then metadata will be parsed from $text. If defined, then metadata embedded in $text will be ignored. Always ignored if $text is undefined. Settings in $meta override * Set settings in plain text.
• $topic - Topic name to check, e.g. 'SomeTopic' *undef to check web perms only)
• $web - Web, e.g. 'Know'

Contributors:
-- MartinCleaver - 23 Jun 2002
-- PeterThoeny - 01 Feb 2004

Discussions

Calls from bin

testwiki$ grep checkAccessPermission bin/*
bin/attach:    if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, "", $topic, $webName ) ) {
bin/edit:    if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, $text, $topic, $webName ) ) {
bin/edit.orig:    if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, $text, $topic, $webName ) ) {
bin/editsection:    if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, $text, $topic, $webName ) ) {
bin/mailtotwiki:        if (! TWiki::Func::checkAccessPermission('CHANGE',
bin/manage:    unless( &TWiki::Access::checkAccessPermission( "manage", $wikiUserName, "",
bin/megarename:             if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, $scantext,
bin/megarename:    if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, $ret, $oldTopic, $oldWeb ) ) {

bin/passwd:        #if( &TWiki::Access::checkAccessPermission( "change", "Main.TWikiGuest", "", $wikiName, $TWiki::mainWebname )) {
bin/poll:    if( ! &TWiki::Func::checkAccessPermission( "vote", $wikiUserName, "", $topic, $webName ) ) {
bin/rdiff:    my $viewAccessOK = &TWiki::Access::checkAccessPermission( "view", $wikiUserName, "", $topic, $webName );
bin/rename:             if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, $scantext,
bin/rename:    if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, $ret, $oldTopic, $oldWeb ) ) {
bin/rename:    if( ! &TWiki::Access::checkAccessPermission( "rename", $wikiUserName, $ret, $oldTopic, $oldWeb ) ) {
bin/save:    if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, "", $topic, $webName ) ) {
bin/savecomment:    if( ! &TWiki::Access::checkAccessPermission( "post", $wikiUserName, "", $topic, $webName ) ) {
bin/savemulti:    if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, "", $topic, $webName ) ) {
bin/upload:    if( ! &TWiki::Access::checkAccessPermission( "change", $wikiUserName, "", $topic, $webName ) ) {
bin/view:    my $viewAccessOK = &TWiki::Access::checkAccessPermission( "view", $wikiUserName, $text, $topic, $webName );
bin/viewauth:    my $viewAccessOK = &TWiki::Access::checkAccessPermission( "view", $wikiUserName, $text, $topic, $webName );

Calls from lib

testwiki$ grep checkAccessPermission lib/TWiki/*
lib/TWiki/Search.pm:                $topicAllowView{ $tempVal } = &TWiki::Access::checkAccessPermission( "view", $TWiki::wikiUserName, $text, $tempVal, $thisWebName );
lib/TWiki/Search.pm:                $topicAllowView{ $tempVal } = &TWiki::Access::checkAccessPermission( "view", $TWiki::wikiUserName, $text, $tempVal, $thisWebName );
lib/TWiki/Search.pm:                $topicAllowView{ $tempVal } = &TWiki::Access::checkAccessPermission( "view", $TWiki::wikiUserName, $text, $tempVal, $thisWebName );
lib/TWiki/Search.pm:                $allowView = &TWiki::Access::checkAccessPermission( "view", $TWiki::wikiUserName, $text, $topic, $thisWebName );
lib/TWiki/Search.pm:                my $changeAccessOK = &TWiki::Access::checkAccessPermission( "change", $TWiki::wikiUserName, $text, $topic, $thisWebName );
lib/TWiki/Store.pm:        $viewAccessOK = &TWiki::Access::checkAccessPermission( "view", $TWiki::wikiUserName, $text, $theTopic, $theWeb );

Issues

userIsInGroup should be declared a Public method or not used in scripts.

However, userIsInGroup() is used in

• bin/edit
• bin/preview
• bin/save
• bin/savemulti

The vector of public methods in the code should be updated to reflect this. -- which code? In access.pm? I see this as saying that userIsInGroup is public [ MartinCleaver 22 Oct 2003 ]

Also consider if userIsInGroup() should be substituted and made private. -- why? and with what?

-- AntonAylward - 10 May 2003

userIsInGroup should be made recursive

By making isUserInGroup check recursively we would enable a group to be a member of a group. I think this simple modification could help manage large installations.

check access for VIEWTOPICRAW and VIEWTOPICHISTORY need to be added

I set up a poll on my system that was supposed to be anonymous. Of course, it isn't because everyone can see the history. So doing a 'Diffs' (Page history) is different to a view and IMO they should be treated differently.

There are many reasons that you'd want to prevent someone from seeing the raw view (e.g. for polls). I think this could also be usefully extended.

-- MartinCleaver - 22 Oct 2003

Added %PERLDOC{...}% to pull the doc from the TWiki.pm Perl module. Removed PublicMethods and PrivateMethods section since they are no longer needed.

-- PeterThoeny - 01 Feb 2004

Set parent topic to CodevDocumentationProject.

-- WalterMundt - 01 Feb 2004

It looks like I am going to need support for more AccessControlFunctions (initially for DeleteAccount, later for TWiki interface to manage groups).

• getGroupsUserIsIn
• removeUserFromGroup
• addUserToGroup
• getAllGroups

PROBLEM!! - how do i get a list of all the groups in a TWiki? in a reasonable amount of time? at the moment I have to do a SEARCH for Set GROUPS yeuch

Search: Set GROUP =

AstroHepBrGroup DevelopBranchGroup Jack2021Group NameGroup SecurityTeamSupportGroup StanStateGroup TWikiAdminGroup TWikiCommunityGroup MochiloncoGroup Sandbox.NVSGroup AutomaticallyPutNewUsersIntoGroup CantAddMyLoginNameToTWikiAdminGroup HowToEmailAGroup RenderListforGroup

-- SvenDowideit - 15 Feb 2004