permissions-requirements.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="permissions-requirements" xreflabel="OpenACS 4 Permissions Requirements">
<title>Permissions Requirements</title>
<authorblurb>
<para>By John McClary Prevost</para>
</authorblurb>
<sect2 id="permissions-requirements-intro">
<title>Introduction</title>
<para>This document records requirements for the OpenACS 4 Permissions system, a
component of the OpenACS 4 Kernel. The Permissions system is meant to unify and
centralize the handling of access and control on a given OpenACS 4 system.</para>
</sect2>
<sect2 id="permissions-requirements-vision">
<title>Vision Statement</title>
<para>Any multi-user software system must address the general problem of
permissions, or "who can do what, on what." On web services, which
typically involve large numbers of users belonging to different groups,
permissions handling is a critical need: access to content, services, and
information generally must be controlled. The OpenACS 4 Permissions system is
meant to serve as a consistent, unified interface for higher-level OpenACS
applications to handle permissions. Consolidating access control in such a
manner reduces both cost and risk: cost, in that less code has to be written
and maintained for dealing with recurring permissions situations; risk, in
that we need not rely on any single programmer's diligence to ensure
access control is implemented and enforced correctly.</para>
<para><emphasis role="strong">Historical Motivations</emphasis></para>
<para>In earlier versions of the OpenACS, permissions and access control was handled
on a module-by-module basis, often even on a page-by-page basis. For example,
a typical module might allow any registered user to access its pages
read-only, but only allow members of a certain group to make changes. The way
this group was determined also varied greatly between modules. Some modules
used "roles", while others did not. Other modules did all access
control based simply on coded rules regarding who can act on a given database
row based on the information in that row.</para>
<para>Problems resulting from this piecemeal approach to permissions and access
control were many, the two major ones being inconsistency, and
repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified,
consistent permissions system that both programmers and administrators can
readily use.</para>
</sect2>
<sect2 id="permissions-requirements-system-overview">
<title>System Overview</title>
<para>The OpenACS 4 Permissions system has two main pieces: first, an API for
developers to readily handle access control in their applications. The second
piece of the system is a UI meant primarily for (subsite) administrators to
grant and revoke permissions to system entities under their control.</para>
<para>Consistency is a key characteristic of the Permissions system - both for a
common administrative interface, and easily deployed and maintained access
control. The system must be flexible enough to support every access model
required in OpenACS applications, but not so flexible that pieces will go unused
or fall outside the common administrative interfaces.</para>
</sect2>
<sect2 id="permissions-requirements-">
<title>Use Cases and User Scenarios</title>
<para><emphasis role="strong">Terminology</emphasis></para>
<para>The primary question an access control system must answer is a three-way
relation, like that between the parts of most simple sentences. A simple
sentence generally has three parts, a subject, an object, and a verb - in the
context of OpenACS Permissions, our simple sentence is, "Can this party
perform this operation on this target?" Definitions:</para>
<para>The subject of the sentence is "<emphasis role="strong">party</emphasis>" - a
distinguishable actor whose access may be controlled, this special word is
used because one person may be represented by several parties, and one party
may represent many users (or no users at all).</para>
<para>The object of the sentence is "<emphasis role="strong">target</emphasis>" - this
is an entity, or object, that the party wishes to perform some action on. An
entity/object here is anything that can be put under access control.</para>
<para>The verb of the sentence is "operation" - a behavior on the OpenACS
system subject to control, this word is used to represent the fact that a
single operation may be part of many larger actions the system wants to
perform. If "foo" is an operation, than we sometimes refer to the
foo "privilege" to mean that a user has the privilege to perform
that operation.</para>
<para>Examples of the essential question addressed by the Permissions system:
Can jane@attacker.com delete the web security forum? Can the Boston office
(a party) within the VirtuaCorp intranet/website create its own news
instance?</para>
</sect2>
<sect2 id="permissions-requirements-links">
<title>Related Links</title>
<itemizedlist>
<listitem><para><xref linkend="permissions-design"/></para></listitem>
</itemizedlist>
</sect2>
<sect2 id="permissions-requirements-func-req">
<title>Functional Requirements</title>
<para><emphasis role="strong">10.0 Granularity</emphasis></para>
<para>The system must support access control down to the level of a single
entity (this would imply down to the level of a row in the OpenACS Objects data
model).</para>
<para><emphasis role="strong">20.0 Operations</emphasis></para>
<para>The system itself must be able to answer the essential permissions
question as well as several derived questions.</para>
<blockquote><para><emphasis role="strong">20.10 Basic Access Check</emphasis></para>
<para>The system must be able to answer the question, "May party P perform
operation O on target T?"</para>
</blockquote><blockquote><para><emphasis role="strong">20.20 Allowed Parties Check</emphasis></para>
<para>The system must be able to answer the question, "Which parties may
perform operation O on target T?"</para>
</blockquote><blockquote><para><emphasis role="strong">20.30 Allowed Operations Check</emphasis></para>
<para>The system must be able to answer the question, "Which operations may
party P perform on target T?"</para>
</blockquote><blockquote><para><emphasis role="strong">20.40 Allowed Targets Check</emphasis></para>
<para>The system must be able to answer the question, "Upon which targets
may party P perform operation O?"</para>
</blockquote>
</sect2>
<sect2 id="permissions-requirements-behave-req">
<title>Behavioral Requirements</title>
<para><emphasis role="strong">40.0 Scale of Privileges</emphasis></para>
<para>Privileges must be designed with appropriate scope for a given OpenACS
package. Some privileges are of general utility (e.g. "read" and
"write"). Others are of more limited use (e.g. "moderate"
- applies mainly to a package like forum, where many users are contributing
content simultaneously). A package defining its own privileges should do so
with moderation, being careful not to overload a privilege like
"read" to mean too many things.</para>
<para><emphasis role="strong">50.0 Aggregation of Operations (Privileges)</emphasis></para>
<para>For user interface purposes, it can be appropriate to group certain
privileges under others. For example, anyone with the "admin"
privilege may also automatically receive "read", "write",
"delete", etc. privileges.</para>
<para><emphasis role="strong">60.0 Aggregation of Parties (Groups)</emphasis></para>
<para>The system must allow aggregation of parties. The exact method used for
aggregation will probably be addressed by the OpenACS 4 "Groups"
system. Regardless of the exact behavior of aggregate parties, if an
aggregate party exists, then access which is granted to the aggregate party
should be available to all members of that aggregate.</para>
<para><emphasis role="strong">70.0 Scope of Access Control</emphasis></para>
<blockquote><para><emphasis role="strong">70.10 Context</emphasis></para>
<para>There must be a method for objects to receive default access control from
some context. For example, if you do not have read access to a forum, you
should not have read access to a message in that forum.</para>
</blockquote><blockquote><para><emphasis role="strong">70.20 Overriding</emphasis></para>
<para>It must be possible to override defaults provided by the context of an
object (as in 70.10), in both a positive and negative manner.</para>
</blockquote>
<blockquote><para><emphasis role="strong">70.20.10 Positive Overriding</emphasis></para>
<para>It must be possible to allow a party more access to some target than they
would get by default. (For example, a user does not have the right to edit
any message on a forum. But a user does possibly have the right to edit
their own messages.)</para>
</blockquote><blockquote><para><emphasis role="strong">70.20.20 Negative Overriding</emphasis></para>
<para>It must be possible to deny a party access to some target that their
inherited privileges would have allowed. (For example, a subdirectory in the
file-storage might normally have its parent directory as context. It should
be possible, however, to make a subdirectory private to some group.)</para>
</blockquote>
<para><emphasis role="strong">100.0 Efficiency</emphasis></para>
<para>At least the basic access check (20.10) and the allowed targets check
(20.40) must be efficient enough for general use, i.e. scalable under fairly
heavy website traffic. It can be expected that almost every page will contain
at least one basic access check, and most pages will contain an allowed
targets check (20.40).</para>
<para>In particular, constraining a <computeroutput>SELECT</computeroutput> to return only rows the
current user has access to should not be much slower than the <computeroutput>SELECT</computeroutput>
on its own.</para>
<para><emphasis role="strong">120.0 Ease of Use</emphasis></para>
<para>Since most SQL queries will contain an allowed target check in the where
clause, whatever mechanism is used to make checks in SQL should be fairly
small and simple.</para>
<para>In particular, constraining a <computeroutput>SELECT</computeroutput> to return only rows the
current user has access to should not add more than one line to a query.</para>
</sect2>
<sect2 id="permissions-requirements-history">
<title>Revision History</title>
<informaltable>
<tgroup cols="4">
<tbody>
<row>
<entry><emphasis role="strong">Document Revision #</emphasis></entry>
<entry><emphasis role="strong">Action Taken, Notes</emphasis></entry>
<entry><emphasis role="strong">When?</emphasis></entry>
<entry><emphasis role="strong">By Whom?</emphasis></entry>
</row>
<row>
<entry>0.1</entry>
<entry>Creation</entry>
<entry>8/17/2000</entry>
<entry>John Prevost</entry>
</row>
<row>
<entry>0.2</entry>
<entry>Revised, updated with new terminology</entry>
<entry>8/25/2000</entry>
<entry>John Prevost</entry>
</row>
<row>
<entry>0.3</entry>
<entry>Edited, reformatted to conform to requirements template, pending
freeze.</entry>
<entry>8/26/2000</entry>
<entry>Kai Wu</entry>
</row>
<row>
<entry>0.4</entry>
<entry>Edited for ACS 4 Beta release.</entry>
<entry>10/03/2000</entry>
<entry>Kai Wu</entry>
</row>
</tbody></tgroup></informaltable>
</sect2>
</sect1>
