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