EXPERTS ONLY Proposed API for user access, for use with TWiki-4.0.x This module will only work with TWiki versions 4.00 and above.

Intended for use with any other plugin that urgently needs access to user data.

The module implements a set of functions for access to TWiki internal user data, to support functions such as getting a list of users, getting a list of groups, and mapping emails to users.

Summary of contents

A single perl module that implements the proposed user access API.

The API is packaged this way so it can be used with TWiki-4.0

Details

getListOfUsers() -> \@list

Get a list of the registered users not including groups. The returned list is a list of TWiki::User objects.

To get a combined list of users and groups, you can do this:

@usersandgroups = ( @{TWiki::Func::getListOfUsers()}, TWiki::Func::getListOfGroups() );

getListOfGroups() -> \@list

Get a list of groups. The returned list is a list of TWiki::User objects.

lookupUser( %spec ) -> \$user

Find the TWiki::User object for a named user.

• %spec - the identifying marks of the user. The following options are supported:
  • wikiname - the wikiname of the user (web name optional, also supports Home)
  • login - login name of the user
  • email - email address of the user

For example,

my $pa = TWiki::Func::lookupUser( email => "pa@addams.org" );
my $ma = TWiki::Func::lookupUser( wikiname => "%MAINWEB%.MorticiaAddams" );

getACLs( \@modes, $web, $topic ) -> \%acls

Get the Access Control Lists controlling which registered users and groups are allowed to access the topic (web).

• \@modes - list of access modes you are interested in; e.g. [ "VIEW","CHANGE" ]
• $web - the web
• $topic - if undef then the setting is taken as a web setting e.g. WEBVIEW. Otherwise it is taken as a topic setting e.g. TOPICCHANGE

\%acls is a hash indexed by user name (web.wikiname). This maps to a hash indexed by access mode e.g. VIEW, CHANGE etc. This in turn maps to a boolean; 0 for access denied, non-zero for access permitted.

my $acls = TWiki::Func::getACLs( [ 'VIEW', 'CHANGE', 'RENAME' ], $web, $topic );
foreach my $user ( keys %$acls ) {
    if( $acls->{$user}->{VIEW} ) {
        print STDERR "$user can view $web.$topic\n";
    }
}

The \%acls object may safely be written to e.g. for subsequent use with setACLs.

Note topic ACLs are not the final permissions used to control access to a topic. Web level restrictions may apply that prevent certain access modes for individual topics.

setACLs( \@modes, $web, $topic, \%acls, $nosearchall )

Set the access controls on the named topic.

• \@modes - list of access modes you want to set; e.g. [ "VIEW","CHANGE" ]
• $web - the web
• $topic - if undef, then this is the ACL for the web. otherwise it's for the topic.
• \%acls - must be a hash indexed by user object. This maps to a hash indexed by access mode e.g. VIEW, CHANGE etc. This in turn maps to a boolean value; 1 for allowed, and 0 for denied. See getACLs for an example of this kind of object.

Access modes used in \%acls that do not appear in \@modes are simply ignored.

If there are any errors, then an Error::Simple will be thrown.

isAdmin() -> $boolean

Find out if the currently logged-in user is an admin or not.

isInGroup( $group ) -> $boolean

Find out if the currently logged-in user is in the named group. e.g.

if( TWiki::Func::isInGroup( "PopGroup" )) {
    ...
}

Contrib Info

Author:	TWiki:Main/CrawfordCurrie http://www.c-dot.co.uk
Version:	9061
Change History:
9060	Removed NOSEARCHALL handling from setACLs
9046	Was not deleting the old setting out of the file, just writing the new setting at the end. Not a killer, just untidy.
8877	Item1701 getting install right
8856	Item1682 Further improvements to the user access, include access to ACL lists (read and write)
8847	Item1670 didn't realise getAllGroups wasn't in TWiki4
8837	Item1670 proof-of-concept demonstrator for functions for user data access from plugins, long overdue.
Copyright ©:	Crawford Currie http://c-dot.co.uk 2006
License:	GNU LGPL
Dependencies:	None
Home:	http://TWiki.org/cgi-bin/view/Plugins/FuncUsersContrib
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/FuncUsersContribDev

Related Topics: TWikiPreferences

-- TWiki:Main/CrawfordCurrie - 11:33:48 04 March 2006