| Prev | Chapter�11.�Development Reference | Next |
|---|
By Pete Su
+ +
+The OpenACS 5.2.3b1 Permissions system allows developers and administrators to
set access control policies at the object level, that is, any
application or system object represented by a row in the
-acs_objects table can be access-controlled via a simple
+acs_objects table can be access-controlled via a simple
PL/SQL or Tcl interface. The permissions system manages a data model
that then allows scripts to check permissions using another simple
API call.
Although this may all sound easy and wonderful, no developer or administrator would want to explicitly set access control rights for every user and every object on a -site. Therefore, OpenACS 5.2.2 has two auxiliary mechanisms for making this +site. Therefore, OpenACS 5.2.3b1 has two auxiliary mechanisms for making this easier: First, the Groups system allows users to be grouped together in flexible ways. Second, the object model defines a notion of object context, which allows applications to group objects together into larger security domains. The rest of this document will talk about each of these parts, and how they fit together with the permissions system. -
In OpenACS 3.x, the groups system allowed developers and administrators to define simple groupings of users. Each group had a human readable name and unique ID, and there was a single mapping table that mapped users to groups. (The actual data model was more complicated because it -contained a meta-data system much like the OpenACS 5.2.2 object type system, +contained a meta-data system much like the OpenACS 5.2.3b1 object type system, but that's not relevant right now.)
The 3.x groups system, while very useful, was limited in few ways. The @@ -47,10 +48,10 @@ member of Greenpeace, its members are not necessarily members of Greenpeace.
-OpenACS 5.2.2 solves both of these modeling problems by introducing a new
+OpenACS 5.2.3b1 solves both of these modeling problems by introducing a new
abstraction called a party. Parties have a recursive
definition, and we can illustrate how it works with the following
-simplified data model. First, we define the parties
+simplified data model. First, we define the parties
table, where each party has an email address and a URL for contact
information.
@@ -78,9 +79,9 @@ )
-The users table is also defined in this data model as a
-subtype of person. It contains many of the basic columns
-that the old OpenACS 3.x users table contained.
+The users table is also defined in this data model as a
+subtype of person. It contains many of the basic columns
+that the old OpenACS 3.x users table contained.
Finally, we define two relations, one for group membership and one for group composition. The composition relation allows us @@ -103,7 +104,7 @@ The full details of the groups data model is beyond the scope of this tutorial - I've just given you what you need to understand how permissions work. For further detail, you can look at Parties in OpenACS 4 or OpenACS 4 Groups Design. -
NOTE: Much more detailed information about the permissions system and how to use it is available in the OpenACS Permissions Tediously Explained document. @@ -113,18 +114,18 @@ already know what parties and objects are, but we don't know what privileges are.
-In OpenACS 5.2.2, a privilege models the right to perform some operation on +In OpenACS 5.2.3b1, a privilege models the right to perform some operation on some object. They are the basic units out of which we build access control policies. For example, in the Unix filesystem we typically implement access control by granting users some combination of -read. write or execute privileges on files and directories. In OpenACS 5.2.2, +read. write or execute privileges on files and directories. In OpenACS 5.2.3b1, the table of privileges is organized hierarchically so that developers can define privileges that aggregate some set of privileges together. For example, if we have read, write, create and delete privileges, it might be convenient to combine them into a new privilege -called "admin". Then if we grant a user this privilege she is +called "admin". Then if we grant a user this privilege she is automatically granted all the child privileges that the privilege -contains. The OpenACS 5.2.2 kernel data model actually defines these +contains. The OpenACS 5.2.3b1 kernel data model actually defines these privileges as follows:
@@ -146,7 +147,7 @@
To give a user permission to perform a particular operation on a
particular object you call
-acs_permission.grant_permission like this:
+acs_permission.grant_permission like this:
@@ -163,12 +164,12 @@ to every object individually: in many cases, we'd prefer controlling permissions to large groups of objects in the site, all at once. We use contexts to achieve this goal. -
-In OpenACS 5.2.2, an object context is a generalization of the scoping -mechanism introduced in OpenACS 3.x. "Scoping" and "scope" are terms best +
+In OpenACS 5.2.3b1, an object context is a generalization of the scoping
+mechanism introduced in OpenACS 3.x. "Scoping" and "scope" are terms best
explained by example: consider some hypothetical rows in the
-address_book table:
-
| ... | scope | user_id | group_id | ... |
|---|---|---|---|---|
| ... | user | 123 | ... | |
| ... | group | 456 | ... | |
| ... | public | ... |
+address_book table: +
| ... | scope | user_id | group_id | ... |
|---|---|---|---|---|
| ... | user | 123 | � | ... |
| ... | group | � | 456 | ... |
| ... | public | � | � | ... |
The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public @@ -179,26 +180,26 @@ person or a group of people or the general public (itself a group of people).
-In OpenACS 5.2.2, rather than breaking the world into a limited set of scopes,
+In OpenACS 5.2.3b1, rather than breaking the world into a limited set of scopes,
every object lives in a single context. A context is just an
another object that represents the security domain to which the object
belongs. By convention, if an object A doesn't have any permissions
explicitly attached to it, then the system will look at the
-context_id column in acs_objects and check
+context_id column in acs_objects and check
the context object there for permissions. Two things control the scope
of this search: the structure of the context hierarchy itself, and the
-value of the security_inherit_p flag in each object. If
-this flag is set to 't', then the automatic search
+value of the security_inherit_p flag in each object. If
+this flag is set to 't', then the automatic search
through the context happens, otherwise it does not. You might set this
-field to 'f' if you want to override the default
+field to 'f' if you want to override the default
permissions in a subtree of some context.
A good example of how to use this hierarchy is in the forums
application. With only row-level permissions it is not obvious how to
reasonably initialize the access control list when creating a
message. At best, we have to explicitly grant various read and write
-privileges whenever we create a message, which is tedious. In OpenACS 5.2.2,
+privileges whenever we create a message, which is tedious. In OpenACS 5.2.3b1,
a reasonable thing to do is to create an object representing a forum,
-and point the context_id field of a new message at the
+and point the context_id field of a new message at the
forum. Then, suppose we grant every user in the system read-access to
this forum. By default, they will automatically have read-access to
the new message we just inserted, since the system automatically
@@ -210,32 +211,32 @@
hierarchy that matches the structure they need for access control in
their application. The following picture shows a typical context
hierarchy for a hypothetical site:
-
+
A few things to note here. First, the top two contexts in the picture
-are "magic" in some sense because they are created by default by OpenACS
-for a specific purpose. The object default_context
+are "magic" in some sense because they are created by default by OpenACS
+for a specific purpose. The object default_context
represents the root of the context hierarchy for the entire site. All
permission searches walk up the tree to this point and then stop. If
you grant permissions on this object, then by default those
permissions will hold for every object in the system, regardless of
which subsite they happen to live in. The object
-security_context_root has a slightly different role. If
+security_context_root has a slightly different role. If
some object has no permissions attached to it, and its value for
-security_inherit_p is 'f', or
-context_id is null, then we use this context by default.
-
At this point, you should either go and download the Notes example
code from the package repository, or check it out of the OpenACS CVS
repository and add it to your server. The package is called
-"notes". To check it out from CVS, read the these instructions
+"notes". To check it out from CVS, read the these instructions
on how to use anonymous checkouts and then
-checkout the module notes:
+checkout the module notes:
The notes code has been modified since this document was written so it is now out of date. See this forum thread.
% export CVSROOT=:pserver:anonymous@cvs.openacs.org:/cvsroot % cvs login # just hit enter when prompted for a password % cvs co notes
After you have downloaded the package, look at the
-index.tcl page in the www directory. You can also
+index.tcl page in the www directory. You can also
look at the code in your browser. The code should look something like this:
@@ -287,8 +288,8 @@
This example shows both the Tcl and PL/SQL APIs for checking
-permissions. The Tcl proc permission::permission_p and the PL/SQL
-function acs_permission.permission_p both return a flag
+permissions. The Tcl proc permission::permission_p and the PL/SQL
+function acs_permission.permission_p both return a flag
indicating whether the current user has permission to perform the
given action. By default, the Tcl procedure extracts the user_id out
of the request environment, while the SQL procedure takes it as an
@@ -304,9 +305,9 @@
see notes that we are allowed to see.
Next, look at the index.adp. It is pretty complicated.
-The main part of this page uses a multiple template
+The main part of this page uses a multiple template
tag. If you want to experiment, you can replace the main body of the
-multiple tag with this:
+multiple tag with this:
<multiple name=notes> @@ -329,7 +330,7 @@
This displays the title of the note as either a link or plain text
depending on whether or not we have write privileges on the object.
-The if tag is something that the OpenACS 5.2.2 template system
+The if tag is something that the OpenACS 5.2.3b1 template system
defines for you to support conditional presentation. The templates developer guide provides more information about this.
If you study the rest of the system, you will also notice that the @@ -342,8 +343,8 @@ implement a user interface that allowed the user to explicitly attach permissions to notes that she wanted to make public or whatever. But that's beyond the scope of this example. -
