Index: openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml,v
diff -u -N -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml 10 Aug 2002 19:34:42 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-design.xml 7 May 2003 00:17:43 -0000 1.3.2.1
@@ -17,9 +17,6 @@
SQL file
-ER diagram
-
-
@@ -29,8 +26,7 @@
The goal of the Permissions system is to provide generic means to both
-programmers and site administrators to designate operations (methods) as
-requiring permissions, and then to check, grant, or revoke permissions via a
+programmers and site administrators to check, grant, or revoke permissions via a
consistent interface. For example, we might decide that the transaction that
bans a user from a sub-site is an operation a site administrator is able to
assign to a particular user. Or perhaps an application developer might decide
@@ -41,23 +37,21 @@
For programmers, the Permissions API provides a means to work with access
control in a consistent manner. If a programmer's OpenACS package defines new
-methods for itself, the Permissions API must provide simple calls to
-determine whether the current user is authorized to perform the given method.
-In addition, using the Permissions API, queries should easily select only
+privilege for itself, the Permissions API must provide simple calls to
+determine whether the current user is has been granted that privilege on a given
+object. In addition, using the Permissions API, queries should easily select only
those package objects on which a user has certain permissions.
For site administrators and other authorized users, the Permissions UI
-provides a means to aggregate the primitive operations (methods) made
-available by the programmer into logical privileges (like read, write, and
-admin) that can be granted and revoked.
+provides a means to grant and revoke privileges on objects.
Historical Considerations
-In earlier versions of the OpenACS, permissions and access control was handled
+In earlier versions of the OpenACS toolkit, 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
@@ -74,18 +68,9 @@
-
-Competitive Analysis
-
-
-None available as of 10/2000.
-
-
-
Design Tradeoffs
-
The core of the permissions data model is quite simple. Unfortunately, the
hierarchical nature of default permissions entails quite a number of tree
queries which could slow the system down. Since every page will have at least
@@ -99,20 +84,10 @@
Data Model Discussion
+The core model consists of three tables:
-As described in section V., the core of the permissions data model is
-simple, though a number of views and auxiliary tables exist to ensure
-adequate performance. The core model consists of five tables:
-
-
-acs_methods
-
-
-The set of all defined methods.
-
-
acs_privileges
@@ -122,15 +97,6 @@
-acs_privilege_method_rules
-
-
-
-A relation describing the set of methods directly
-associated with each privilege.
-
-
-
acs_privilege_hierarchy
@@ -146,9 +112,8 @@
A table with one (party, object, privilege)
row for every privilege directly granted on any object in
-the system - this is a denormalization of
-acs_privilege_method_rules and
-acs_privilege_hierarchy
+the system.
+
@@ -163,15 +128,7 @@
information:
-
-acs_privilege_method_map
-
-
-Map of privileges to the methods they contain either directly or because
-of another privilege which is included (at any depth).
-
-
acs_object_grantee_priv_map
@@ -189,30 +146,19 @@
Relation on (object, party, privilege) for
privileges directly from acs_object_grantee_priv_map or also because
-a party is a member of a group (at any depth).
+a party is a member of a group (at any depth). This view is normally used in an exists
+clause to constrain the rows returned by a query to those on which a given party has a given privilege.
-
-acs_object_party_method_map
-
-
-
-Relation with every (object, party, method)
-tuple implied by the above trees.
-
-In general, only acs_object_party_method_map
-should be used for queries from other modules. The other views are
-intermediate steps in building that query.
-
The data model also includes two simple PL/SQL procedures
(acs_permission.grant_permission and
acs_permission.revoke_permission) for granting and revoking a
specific privilege for a specific user on a specific object.
To sum up, the PL/SQL procedures are meant to be used to grant or revoke
-permissions. The five base tables represent the basic data model of the
+permissions. The three base tables represent the basic data model of the
system, with a set of views provided to convert them into a format suitable
for joining to answer specific questions. The exact means by which this
transformation takes place should not be depended on, since they may change
@@ -225,10 +171,6 @@
parties get the privileges of any groups they are directly or indirectly
a member of
-privileges get associated with the methods of any other privileges they
-have taken methods from (at any level) (see
-acs_privilege_hierarchy)
-
objects get access control from direct grants, or inherit permissions
from their context (unless the "don't inherit" flag is
set)
@@ -240,30 +182,37 @@
Legal Transactions
-There are three essential areas in which all transactions in the
-permissions system fall:
+There are two essential areas in which all transactions in the
+permissions system fall (a privilege is a an operation like "read",
+permissions define which parties have which privileges on which
+objects):
-Modification of methods and privileges
+Modification of privileges
+
Modification of permissions
Queries on permissions
-"Modification of methods and privileges." This
+"Modification of privileges." This
refers to actions that happen mainly at package installation time - a package
-will create a number of methods for its own use, then associate them with the
-system's standard privileges, or new privileges which the package has
-created. The association step might also happen later, if the site-wide
-administrator chooses to change permissions policy.
+may create new privileges and aggregations of privileges. This should be done with care, as
+each additional privilege and parent-child privilege relationship added to the system
+decreases the performance of the permissions system. Historically, packages have created
+their own versions of common privileges like "read" or "write" rather than use the global
+permissions created by the kernel. This practice is now discouraged as it adds no
+usable functionality, makes the design and implementation of general-purpose permissions UI pages
+more difficult, and as mentioned previously negatively impacts performance.
+
These steps involve directly manipulating the acs_methods,
acs_privileges, and acs_privilege_method_rules tables. A
web page for manipulating these features should be limited to site-wide
administrators.
-"Modification of permissions" - involves fairly
+"Modification of permissions." - involves fairly
common operations. Users are typically able to administer permissions for
objects they themselves create. The two basic operations here are
"grant" and "revoke". Granting permissions is done via
@@ -273,24 +222,22 @@
Web pages for making these changes are available to all users, so they
should not be in an admin area. In order to grant and revoke permissions on
-an object, the user must have the administer_privileges method
-permission on that object.
+an object, the user must have the admin
+privilege on that object.
"Queries on permissions" - by far the most
common operation is querying the permissions database. Several kinds of
questions are commonly asked: First, and most commonly, "Can this party
-perform this method on this object?" Two Tcl functions are provided to
+perform this operation on this object?" Two Tcl functions are provided to
answer this - one which returns a boolean, the other of which results in an
-error page. These tcl functions directly access the
-acs_object_party_method_map.
+error page.
The second most commonly asked question occurs when a list of objects is
-being displayed, often in order to provide appropriate UI functionality:
-"For this party, what methods are available on these objects?"
+being displayed, often in order to provide appropriate UI functionality.
Here, the SQL query needs to filter based on whether the party/user can
-perform some operation on the object. This is done via a join or sub-select
-against acs_object_party_method_map, or by calling the Tcl functions
-for appropriate methods.
+perform some operation on the object. This is done by using an exists
+clause that returns a value if any row exists in the acs_object_party_privilege_map
+view with the given party, object and privilege.
Finally, when administering the permissions for an object, a web page
needs to know all permissions directly granted on that object. This is done
@@ -305,29 +252,24 @@
The API to the permissions system consists of a few well-known tables,
plus a pair of PL/SQL procedures and a pair of Tcl functions.
-Tables
+Tables and views
-acs_methods, acs_privileges, and
-acs_privilege_method_rules manage the set of permissions in the
-system. At installation time, a package will add to these three tables to
-introduce new permissions into the system.
+The main view for queries is acs_object_party_privlege_map, which
+contains (object, party, privilege) triples
+for all allowed operations in the system.
-The main table for queries is acs_object_party_method_map, which
-contains (object, party, method) triples for all
-allowed operations in the system.
-
Also of interest for queries is acs_permissions, which lists
-directly granted privileges. Neither acs_object_party_method_map
+directly granted privileges. Neither acs_object_party_privilege_map
(which is a view) nor acs_permissions should be updated
directly.
-PL/SQL Procedures
+PL/[pg]SQL Procedures
acs_permissions.grant_permission introduces new permissions for
an object. It should be given an (object, party,
privilege) triple, and will always succeed. If the permission is
-already in the system, no change occurs. The interface for this procedure
-is:
+already in the system, no change occurs.
+The interface for this procedure is:
procedure grant_permission (
@@ -361,14 +303,13 @@
To receive a true or false value, Tcl code should call:
-ad_permission_p $object_id $object_type $method -user_id $user_id
+permission::permission_p -party_id $party_id -object_id $object_id -privilege $privilege
-If the user_id argument is left out, then the currently logged in
-user is checked. To create an error page, Tcl code should call:
+To create an error page, Tcl code should call:
-ad_require_permission $object_id $object_type $method
+permission::require_permission -party_id $party_id -object_id $object_id -privilege $privilege
These procedures are defined in acs-permissions-procs.tcl.
@@ -380,7 +321,7 @@
All users of the permissions system are the same at the user-interface
-level. If you have the administer_privileges method permission on an
+level. If you have the admin privilege on an
object, then you may edit privileges for that object with the UI.
The UI currently provides a list of all granted permissions on the object.
@@ -444,19 +385,19 @@
-System owner
+System maintainer
-Rafael H. Schloming
+Don Baccus
Documentation author
-John Prevost
+John Prevost
@@ -490,6 +431,13 @@
10/04/2000
Kai Wu
+
+
+0.3
+Edited for OpenACS 4.6.3
+05/04/2003
+Don Baccus
+
Index: openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml,v
diff -u -N -r1.3 -r1.3.2.1
--- openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml 10 Aug 2002 19:34:42 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/permissions-requirements.xml 7 May 2003 00:17:43 -0000 1.3.2.1
@@ -229,16 +229,11 @@
clause, whatever mechanism is used to make checks in SQL should be fairly
small and simple.
-In particular, constraining a SELECT to return only rows the
-current user has access to should not add more than one line to a query.
-
-
Revision History
-
@@ -278,6 +273,14 @@
10/03/2000
Kai Wu
+
+
+0.5
+Edited for OpenACS 4.6.3 release.
+05/04/2003
+Don Baccus
+
+