Permission Package

part of the ArsDigita Community System by Tracy Adams

User directory: none
Admin directory: everything is done in the existing user group directory /admin/ug/ (this package builds on user groups)
data model: subsection within /doc/sql/user-groups.sql
procedures: mostly within /tcl/ad-user-groups.tcl

The Big Picture

We want a standardized way of asking "Is user x allowed to do y?"

The Medium-sized Picture

We define a table

create table administration_info (
 	group_id	integer not null references user_groups,
	module		varchar(300) not null,
	submodule	varchar(300),
	unique(module, submodule, group_id)
);

This allows us to associate a user group with administration of a particular section of a site. In general, these user groups will have a group type of "administration". The extra columns for a user group of this type are "module" and "submodule".

The other key feature of this software package is a set of Tcl procedures that developers can call to find out of a user has appropriate permissions. These procedures may elect to cache. For example, we expect pages to call ad_permission_p to find out whether a user is authorized to perform a particular action.

create table user_group_action_role_map (
	group_id     	integer not null references user_groups,
	role		varchar(200) not null,
	action		varchar(200) not null,
	creation_date        date not null,	
	creation_user        integer not null references users,
	creation_ip_address  varchar(200) not null,
	primary key (group_id, role, action) );

Definitions

Site-wide administrator: A person with access to the site-wide (/admin) pages. These pages are generally password-protected with AOLserver and users access these pages with https. Some pages underneath /admin demand that the user be logged in, but we've been sloppy about requiring administration group membership for this user.
Group administrator: A person with the role of "administrator" in a user group has the power to approve or reject applications by others for group membership. Group administrators implicitly have all the authority of users with any other role in the group.
Content administrators: A person with some role in a user group associated with a module (or module/submodule combination).

The Steps

Consider applying this package to a legacy ACS module such as the classified ad system (/gc/). Here are the steps:

decide whether we are going to permission the entire system or elect content administrators on a per-domain basis (assume that we decide to go per-domain)
decide whether you need basic or multi-role permissions; in the "basic" case, everyone in the administration group with the roles of either "all" or "administrator" will have privileges according to ad_permission_p. In the multi-role case, ad_permission_p will explore the user_group_action_role_map table to find out whether a user with a particular role can perform the specified action. (assume that we decide to use the basic system)
create administration groups for each existing classified ad domain, using ad_administration_group_add or its PL/SQL counterpart.
insert a call to ad_administration_group_add in the code that creates a new classified ad domain
insert calls to ad_permission_p anywhere in the /gc/ pages that you want to check authorizations
visit the /admin/ug/ pages to assign users to the created administration groups

Apply the permissions package to modules that already have user groups

If you already have a user group associated with your module, you do not have to create a group of type "administration"; you can use the lower-level generic helper procedures below.

Multi-Role

For some applications, roles of "administrator" and "all" are not sufficient. For example, we've used this package in a system that keeps electronic medical records. We needed to restrict access to various pages depending on the user's role in the hospital. Some users were allowed access to full patient records, while others were only allowed to enter demographic information.

You specify multi-role permissions when you create a group with ad_administration_group_add or by toggle the multi-role perms column in /admin/ug/group.tcl. A group of any type, i.e., even one that isn't "administration" can be the basis of a multi-role permission scheme.

Once multi-role perms are enabled, the /admin/ug/group.tcl page will sprout some new user interface. The basic idea is that you add roles and actions until you're looking at a matrix of which roles are authorized to perform which actions. You could also fill this matrix programmatically by calling the procedures ad_administration_group_role_add, ad_administration_group_action_add, ad_administration_group_action_role_map.

Administration group type procedures

Groups of type administration can be identified by their module and submodule.

To answer "Is user x allowed to do y?" ad_permission_p
To see if a user is in the group: ad_administration_group_member
Create a group of type administration: ad_administration_group_add or the pls-sql procedure administration_group_add
To grant a user a role in an administration group: ad_administration_group_user_add
To add a role to an administration group: ad_administration_group_role_add
To add an action to an administration group: ad_administration_group_action_add
To allow users with a role to execute an action: ad_administration_group_action_role_map
To retrieve a group_id from an adminsitration group's module and submodule: ad_administration_group_id

Generic procedures

Group_id will identify any group, regardless of type. Both basic and multi-role permission schemes will work.

To answer "Is user x allowed to do y?" ad_permission_p
To see if a user is in the group: ad_user_group_member
To answer "Is the user an administrator of this group?" ad_user_group_authorized_admin
To answer "Is the user an administrator of this group? (or a site-wide administrator with uber-user privileges)" ad_user_group_authorized_admin_or_site_admin
To retrieve a group_id from an adminsitration group's module and submodule: ad_administration_group_id
To add an user group: ad_user_group_add
To grant a user a role: ad_user_group_user_add
To add a role: ad_user_group_role_add
To add an action: ad_user_group_action_add
To allow users with a role to execute an action: ad_user_group_action_role_map

teadams@mit.edu