- I OpenACS For Everyone
- I.1 High level information: What is OpenACS?
- I.1.1 Overview
- I.1.2 OpenACS Release Notes
- I.2 OpenACS: robust web development framework
- I.2.1 Introduction
- I.2.2 Basic infrastructure
- I.2.3 Advanced infrastructure
- I.2.4 Domain level tools
- I.1 High level information: What is OpenACS?
- II Administrator's Guide
- II.2 Installation Overview
- II.2.1 Basic Steps
- II.2.2 Prerequisite Software
- II.3 Complete Installation
- II.3.1 Install a Unix-like system and supporting software
- II.3.2 Install Oracle 10g XE on debian
- II.3.2.1 Install Oracle 8.1.7
- II.3.3 Install PostgreSQL
- II.3.4 Install AOLserver 4
- II.3.5 Quick Install of OpenACS
- II.3.5.1 Complex Install OpenACS 5.3
- II.3.6 OpenACS Installation Guide for Windows2000
- II.3.7 OpenACS Installation Guide for Mac OS X
- II.4 Configuring a new OpenACS Site
- II.4.1 Installing OpenACS packages
- II.4.2 Mounting OpenACS packages
- II.4.3 Configuring an OpenACS package
- II.4.4 Setting Permissions on an OpenACS package
- II.4.5 How Do I?
- II.4.6 Configure OpenACS look and feel with templates
- II.5 Upgrading
- II.5.1 Overview
- II.5.2 Upgrading 4.5 or higher to 4.6.3
- II.5.3 Upgrading OpenACS 4.6.3 to 5.0
- II.5.4 Upgrading an OpenACS 5.0.0 or greater installation
- II.5.5 Upgrading the OpenACS files
- II.5.6 Upgrading Platform components
- II.6 Production Environments
- II.6.1 Starting and Stopping an OpenACS instance.
- II.6.2 AOLserver keepalive with inittab
- II.6.3 Running multiple services on one machine
- II.6.4 High Availability/High Performance Configurations
- II.6.5 Staged Deployment for Production Networks
- II.6.6 Installing SSL Support for an OpenACS service
- II.6.7 Set up Log Analysis Reports
- II.6.8 External uptime validation
- II.6.9 Diagnosing Performance Problems
- II.7 Database Management
- II.7.1 Running a PostgreSQL database on another server
- II.7.2 Deleting a tablespace
- II.7.3 Vacuum Postgres nightly
- II.8 Backup and Recovery
- II.8.1 Backup Strategy
- II.8.2 Manual backup and recovery
- II.8.3 Automated Backup
- II.8.4 Using CVS for backup-recovery
- II.A Install Red Hat 8/9
- II.B Install additional supporting software
- II.B.1 Unpack the OpenACS tarball
- II.B.2 Initialize CVS (OPTIONAL)
- II.B.3 Add PSGML commands to emacs init file (OPTIONAL)
- II.B.4 Install Daemontools (OPTIONAL)
- II.B.5 Install qmail (OPTIONAL)
- II.B.6 Install Analog web file analyzer
- II.B.7 Install nspam
- II.B.8 Install Full Text Search
- II.B.9 Install Full Text Search using Tsearch2
- II.B.10 Install Full Text Search using OpenFTS (deprecated see tsearch2)
- II.B.11 Install nsopenssl
- II.B.12 Install tclwebtest.
- II.B.13 Install PHP for use in AOLserver
- II.B.14 Install Squirrelmail for use as a webmail system for OpenACS
- II.B.15 Install PAM Radius for use as external authentication
- II.B.16 Install LDAP for use as external authentication
- II.B.17 Install AOLserver 3.3oacs1
- II.C Credits
- II.C.1 Where did this document come from?
- II.C.2 Linux Install Guides
- II.C.3 Security Information
- II.C.4 Resources
- II.2 Installation Overview
- III For OpenACS Package Developers
- III.9 Development Tutorial
- III.9.1 Creating an Application Package
- III.9.2 Setting Up Database Objects
- III.9.3 Creating Web Pages
- III.9.4 Debugging and Automated Testing
- III.10 Advanced Topics
- III.10.1 Write the Requirements and Design Specs
- III.10.2 Add the new package to CVS
- III.10.3 OpenACS Edit This Page Templates
- III.10.4 Adding Comments
- III.10.5 Admin Pages
- III.10.6 Categories
- III.10.7 Profile your code
- III.10.8 Prepare the package for distribution.
- III.10.9 Distributing upgrades of your package
- III.10.10 Notifications
- III.10.11 Hierarchical data
- III.10.12 Using .vuh files for pretty urls
- III.10.13 Laying out a page with CSS instead of tables
- III.10.14 Sending HTML email from your application
- III.10.15 Basic Caching
- III.10.16 Scheduled Procedures
- III.10.17 Enabling WYSIWYG
- III.10.18 Adding in parameters for your package
- III.10.19 Writing upgrade scripts
- III.10.20 Connect to a second database
- III.10.21 Future Topics
- III.11 Development Reference
- III.11.1 OpenACS Packages
- III.11.2 OpenACS Data Models and the Object System
- III.11.3 The Request Processor
- III.11.4 The OpenACS Database Access API
- III.11.5 Using Templates in OpenACS
- III.11.6 Groups, Context, Permissions
- III.11.7 Writing OpenACS Application Pages
- III.11.8 Parties in OpenACS
- III.11.9 OpenACS Permissions Tediously Explained
- III.11.10 Object Identity
- III.11.11 Programming with AOLserver
- III.11.12 Using Form Builder: building html forms dynamically
- III.12 Engineering Standards
- III.12.1 OpenACS Style Guide
- III.12.2 Release Version Numbering
- III.12.3 Constraint naming standard
- III.12.4 ACS File Naming and Formatting Standards
- III.12.5 PL/SQL Standards
- III.12.6 Variables
- III.12.7 Automated Testing
- III.13 CVS Guidelines
- III.13.1 Using CVS with OpenACS
- III.13.2 OpenACS CVS Concepts
- III.13.3 Contributing code back to OpenACS
- III.13.4 Additional Resources for CVS
- III.14 Documentation Standards
- III.14.1 OpenACS Documentation Guide
- III.14.2 Using PSGML mode in Emacs
- III.14.3 Using nXML mode in Emacs
- III.14.4 Detailed Design Documentation Template
- III.14.5 System/Application Requirements Template
- III.15 TCLWebtest
- III.16 Internationalization
- III.16.1 Internationalization and Localization Overview
- III.16.2 How Internationalization/Localization works in OpenACS
- III.16.4 Design Notes
- III.16.5 Translator's Guide
- III.D Using CVS with an OpenACS Site
- III.9 Development Tutorial
- IV For OpenACS Platform Developers
- IV.17 Kernel Documentation
- IV.17.1 Overview
- IV.17.2 Object Model Requirements
- IV.17.3 Object Model Design
- IV.17.4 Permissions Requirements
- IV.17.5 Permissions Design
- IV.17.6 Groups Requirements
- IV.17.7 Groups Design
- IV.17.8 Subsites Requirements
- IV.17.9 Subsites Design Document
- IV.17.10 Package Manager Requirements
- IV.17.11 Package Manager Design
- IV.17.12 Database Access API
- IV.17.13 OpenACS Internationalization Requirements
- IV.17.14 Security Requirements
- IV.17.15 Security Design
- IV.17.16 Security Notes
- IV.17.17 Request Processor Requirements
- IV.17.18 Request Processor Design
- IV.17.19 Documenting Tcl Files: Page Contracts and Libraries
- IV.17.20 Bootstrapping OpenACS
- IV.17.21 External Authentication Requirements
- IV.18 Releasing OpenACS
- IV.18.1 OpenACS Core and .LRN
- IV.18.2 How to Update the OpenACS.org repository
- IV.18.3 How to package and release an OpenACS Package
- IV.18.4 How to Update the translations
- IV.17 Kernel Documentation
- V Tcl for Web Nerds
- V.1 Tcl for Web Nerds Introduction
- V.2 Basic String Operations
- V.3 List Operations
- V.4 Pattern matching
- V.5 Array Operations
- V.6 Numbers
- V.7 Control Structure
- V.8 Scope, Upvar and Uplevel
- V.9 File Operations
- V.10 Eval
- V.11 Exec
- V.12 Tcl for Web Use
- V.13 OpenACS conventions for TCL
- V.14 Solutions
- VI SQL for Web Nerds
- VI.1 SQL Tutorial
- VI.1.1 SQL Tutorial
- VI.1.2 Answers
- VI.2 SQL for Web Nerds Introduction
- VI.3 Data modeling
- VI.3.1 The Discussion Forum -- philg's personal odyssey
- VI.3.2 Data Types (Oracle)
- VI.3.4 Tables
- VI.3.5 Constraints
- VI.4 Simple queries
- VI.5 More complex queries
- VI.6 Transactions
- VI.7 Triggers
- VI.8 Views
- VI.9 Style
- VI.10 Escaping to the procedural world
- VI.11 Trees
- VI.1 SQL Tutorial
IV.17.5 Permissions Design
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 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 that viewing a certain set of pages within the application is an operation to be individually granted or revoked from a user. It's expected that the Permissions system will be seeing a lot of use - almost every page will make at least one permissions API call, and some will make several.
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 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.
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.
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.
None available as of 10/2000.
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 one permissions check, a number of views and auxiliary tables (de-normalizations of the data model) have been created to speed up access queries. As a consequence, speed of updates are decreased and requirements for additional storage space increase.
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:
The set of all defined methods.
The set of all defined privileges.
A relation describing the set of methods directly associated with each privilege.
A relation describing which privileges directly "contain" other privileges.
A table with one (party, object, privilege) row for every privilege directly granted on any object in the system - this is a denormalization of
There are also a number of views to make it easier to ask specific questions about permissions. For example, a number of the above tables describe "direct" or explicit permissions. Inheritance and default values can, however, introduce permissions which are not directly specified. (For example, read access on a forum allows read access on all the messages in the forum.)
The following views provide flattened versions of inherited information:
Map of privileges to the methods they contain either directly or because of another privilege which is included (at any depth).
Relation on (object, party, privilege) for privileges from
acs_privileges) granted directly on the object, or on the context of the object (at any depth).
Relation on (object, party, privilege) for privileges directly from
acs_object_grantee_priv_mapor also because a party is a member of a group (at any depth).
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.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 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 for efficiency reasons.
The transformations done create a set of default permissions, in which:
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
objects get access control from direct grants, or inherit permissions from their context (unless the "don't inherit" flag is set)
There are three essential areas in which all transactions in the permissions system fall:
Modification of methods and privileges
Modification of permissions
Queries on permissions
"Modification of methods and 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.
These steps involve directly manipulating the
acs_privilege_method_rules tables. A web page for manipulating these features should be limited to site-wide administrators.
"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
acs_permissions.grant_permission, and revocation via
acs_permissions.revoke_permission. These directly manipulate the
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.
"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 answer this - one which returns a boolean, the other of which results in an error page. These tcl functions directly access the
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?" 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.
Finally, when administering the permissions for an object, a web page needs to know all permissions directly granted on that object. This is done by querying against
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.
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 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 (which is a view) nor
acs_permissions should be updated directly.
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:
procedure grant_permission ( object_id acs_permissions.object_id%TYPE, grantee_id acs_permissions.grantee_id%TYPE, privilege acs_permissions.privilege%TYPE );
acs_permissions.revoke_permission removes a permission entry given a triple. It always succeeds--if a permission does not exist, nothing changes. The interface for this procedure is:
procedure revoke_permission ( object_id acs_permissions.object_id%TYPE, grantee_id acs_permissions.grantee_id%TYPE, privilege acs_permissions.privilege%TYPE );
These procedures are defined in
Two tcl procedures provide a simple call for the query, "Can this user perform this method on this object?" One returns true or false, the other presents an error page.
To receive a true or false value, Tcl code should call:
ad_permission_p $object_id $object_type $method -user_id $user_id
user_id argument is left out, then the currently logged in user is checked. To create an error page, Tcl code should call:
ad_require_permission $object_id $object_type $method
These procedures are defined in
All users of the permissions system are the same at the user-interface level. If you have the
administer_privileges method permission 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. If the user wishes to revoke privileges, she may select a set of grants, choose revoke, confirm their deletion, and be returned to the same page after those privileges have been revoked.
Granting permissions currently (as of 10/2000) works by providing a list of all possible permissions and a list of all parties in the system. (For large sites, some future search mechanism will be necessary.) After choosing privileges to grant, the user is returned to the "edit privileges for one object" screen.
If it makes sense, the system will also display a checkbox which the user may select to toggle whether permissions are inherited from the object's context.
There are a number of potential future enhancements for the permissions UI, outlined below.
There are no configuration options for the permissions system.
The most important future changes to the Permissions system are likely to be in the UI:
There should be a page displaying a list of all objects for which the current user is allowed to administer privileges.
Users should be able to view the permissions on any object, or perhaps on objects which they have the "read_permissions" method. This would allow them to see what grants are affecting their objects through inheritance.
- System creator
- System owner
- Documentation author
|Document Revision #||Action Taken, Notes||When?||By Whom?|
|0.2||Edited for ACS 4 Beta release||10/04/2000||Kai Wu|