Index: openacs-4/packages/acs-core-docs/www/permissions.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v diff -u -r1.43 -r1.43.4.1 --- openacs-4/packages/acs-core-docs/www/permissions.html 5 Aug 2006 05:18:20 -0000 1.43 +++ openacs-4/packages/acs-core-docs/www/permissions.html 3 Feb 2008 12:07:40 -0000 1.43.4.1 @@ -1,11 +1,12 @@ -
By Pete Su
+ +By Pete Su
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
+The OpenACS 5.4.0 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
+acs_objects table can be access-controlled via a
PL/SQL or Tcl interface. The permissions system manages a data model
that then allows scripts to check permissions using another API call.
@@ -19,10 +20,10 @@ together into larger security domains.
The rest of this document discusses each of these parts, and how they fit together with the permissions system. -
+OpenACS 5.4.0 has an abstraction called a party. Parties have a recursive
definition. 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.
@@ -50,8 +51,8 @@ )
-The users
table is also defined in this data model as a
-subtype of person
.
+The users table is also defined in this data model as a
+subtype of person.
Finally, we define two relations, one for group membership and one for group composition. @@ -70,7 +71,7 @@
The full details of the groups data model is beyond the scope of this tutorial. See Parties in OpenACS or OpenACS 4 Groups Design for more details. -
NOTE: Much more detailed information about the permissions system and how to use it is available in the OpenACS Permissions Tediously Explained document. @@ -83,14 +84,14 @@ some object. Privileges are the basic units out of which we build access control policies. For example in the Unix filesystem, access is controlled by granting users some combination of read, write, or execute privileges on files and directories. In -OpenACS 5.2.3rc1, +OpenACS 5.4.0, 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, when a user is granted "admin" privilege, she is +called "admin". Then, when a user is granted "admin" privilege, she is automatically granted all the child privileges that the privilege -contains. The OpenACS 5.2.3rc1 kernel data model defines these +contains. The OpenACS 5.4.0 kernel data model defines these privileges:
# @@ -116,7 +117,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:# sql code @@ -134,12 +135,12 @@ would become very tedious. OpenACS provides a object contexts as a means for controlling permissions of a large group of objects at the same time. -
-In OpenACS 5.2.3rc1, object context is a scoping -mechanism. "Scoping" and "scope" are terms best +
+In OpenACS 5.4.0, object context is a scoping
+mechanism. "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
@@ -152,25 +153,25 @@
another object that represents the security domain to which the object
belongs. By convention, if an object A does not 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
+the value of the security_inherit_p
flag in each object.
If
-security_inherit_p
flag is set to 't'
, then the automatic search
+security_inherit_p 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.
For an example of how to use context hierarchy, consider 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.
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
@@ -182,23 +183,23 @@
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:
-
+
The top two contexts in the diagram
-are called "magic" numbers, because in some sense, they are created by default by OpenACS
-for a specific purpose. The object default_context
+are called "magic" numbers, because in some sense, 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, this context is used by default.
+security_inherit_p is 'f', or
+context_id is null, this context is used by default.
See the package developer tutorials for examples on how to use permissions code. -