ArsDigita Archives

Permission Package

part of the ArsDigita Community System by Tracy Adams

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) );


  • 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.


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. 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 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.

Generic procedures

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