| Prev | Chapter 11. Development Reference | Next |
|---|
+
by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello -
- -The code has been modified since this document was written so it is now out of date. See this forum thread.
- -Who +
The code has been modified since this document was written so it is now out of date. See this forum thread.
Who
(grantee_id) can do what
(privilege) on which object
(object_id).
-
+
The general permissions system has a flexible (and relatively complex) data model in OpenACS. Developers who have not had the time to learn the internals of the data model may end up writing seemingly correct code that crashes their system in @@ -27,16 +17,12 @@ Groups, Context, Permissions documentation, but who have not had the opportunity to take a long, careful look at the system internals. -
- -+
In OpenACS, most of the interesting tables are expected to extend (subtype)
the acs_objects table, i.e. they are expected to have an integer
primary key column that references the object_id column of
acs_objects.
-
+create table acs_objects ( object_id integer not null @@ -59,33 +45,24 @@ constraint acs_objects_context_object_un unique (context_id, object_id) disable ); -- -+
This means that items that want to use the features of the
OpenACS object system needs to have an entry in the acs_objects. This
allows developers to define relationships between any two entities A
and B by defining a relationship between their corresponding entries
in the acs_objects table. One of the applications of this
powerful capability is the general permissions system.
-
+
At the heart of the permission system are two tables: acs_privileges
and acs_permissions.
-
+create table acs_privileges ( privilege varchar2(100) not null constraint acs_privileges_pk primary key, pretty_name varchar2(100), pretty_plural varchar2(100) ); -- -+create table acs_permissions ( object_id not null @@ -99,59 +76,36 @@ constraint acs_permissions_pk primary key (object_id, grantee_id, privilege) ); -- -+
The acs_privileges table stores
named privileges like read,
write, delete, create, and
admin. The acs_permissions
table stores assertions of the form:
-
+
Who (grantee_id) can do what (privilege)
on which object (object_id).
-
+
The micromanaging approach to system security would be to require application developers to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users who have the read privilege on all objects, then we would need to store 100,000,000 entries of the form: -
- -| object_id | grantee_id | privilege |
|---|---|---|
| object_id_1 | user_id_1 | 'read' |
| object_id_1 | user_id_2 | 'read' |
| ... | ||
| object_id_1 | user_id_n | 'read' |
| object_id_2 | user_id_1 | 'read' |
| object_id_2 | user_id_2 | 'read' |
| ... | ||
| object_id_2 | user_id_n | 'read' |
| ... | ||
| ... | ||
| object_id_m | user_id_1 | 'read' |
| object_id_m | user_id_2 | 'read' |
| ... | ||
| object_id_m | user_id_n | 'read' |
+
| object_id | grantee_id | privilege |
|---|---|---|
| object_id_1 | user_id_1 | 'read' |
| object_id_1 | user_id_2 | 'read' |
| ... | ||
| object_id_1 | user_id_n | 'read' |
| object_id_2 | user_id_1 | 'read' |
| object_id_2 | user_id_2 | 'read' |
| ... | ||
| object_id_2 | user_id_n | 'read' |
| ... | ||
| ... | ||
| object_id_m | user_id_1 | 'read' |
| object_id_m | user_id_2 | 'read' |
| ... | ||
| object_id_m | user_id_n | 'read' |
Although quite feasible, this approach fails to take advantage of the fact that objects in the system are commonly organized hierarchally, and permissions usually follow the hierarchical structure, so that if user X has the read privilege on object A, she typically also has the read privilege on all objects attached under A. -
-+
The general permission system takes advantage of the hierarchical organization of objects to unburden developers of the necessity to explicitly maintain security information for every single object. There are three kinds of hierarchies involved. These are discussed in the following sections. -
-Suppose objects A, B, ..., and F form the following hierarchy. -
- -This can be represented in the acs_objects table by the following entries: -
- -+
The first entry tells us that object 20 is the descendant of object 10, and the third entry shows that object 40 is the descendant of object 20. By running a CONNECT BY query, we can compute that object 40 is the second-generation descendant of object 10. With this in mind, if we want to record the fact that user Joe has the read privilege on objects A, ..., F, we only need to record one entry in the acs_permissions table. -
- -| object | grantee | privilege |
|---|---|---|
| A | Joe | read |
+
| object | grantee | privilege |
|---|---|---|
| A | Joe | read |
The fact that Joe can also read B, C, ..., and F can be derived by ascertaining that these objects are children of A by traversing the context hierarchy. As it turns out, hierarchical queries are expensive. As Rafael Schloming put it so aptly, Oracle can't deal with hierarchies for shit. -
- -+
One way to solve this problem is to cache a flattened view of the context tree like so: -
- -| object | ancestor | n_generations |
|---|---|---|
| A | A | 0 |
| B | B | 0 |
| B | A | 1 |
| C | C | 0 |
| C | A | 1 |
| D | D | 0 |
| D | B | 1 |
| D | A | 2 |
| E | E | 0 |
| E | B | 1 |
| E | A | 2 |
| F | F | 0 |
| F | C | 1 |
| F | A | 2 |
+
| object | ancestor | n_generations |
|---|---|---|
| A | A | 0 |
| B | B | 0 |
| B | A | 1 |
| C | C | 0 |
| C | A | 1 |
| D | D | 0 |
| D | B | 1 |
| D | A | 2 |
| E | E | 0 |
| E | B | 1 |
| E | A | 2 |
| F | F | 0 |
| F | C | 1 |
| F | A | 2 |
Note that the number of entries in the flattened view grows exponentially with respect to the depth of the context tree. For instance, if you have a fully populated binary tree with a depth of n, then the number of entries in its flattened view is -
- -- 1 + 2*2 + 3*4 + 4*8 + 5*16 + ... + (n+1)*2n = n*2n+1 + 1
- -+
+ 1 + 2*2 + 3*4 + 4*8 + 5*16 + ... + (n+1)*2n = n*2n+1 + 1
Despite its potentially great storage costs, maintaining a
flattened representation of the context tree is exactly what OpenACS
does. The flattened context tree is stored in the
acs_object_context_index table.
-
+create table acs_object_context_index ( object_id not null @@ -256,9 +180,7 @@ constraint acs_object_context_index_pk primary key (object_id, ancestor_id) ) organization index; -- -+
A few things to note about this table are these. Number one, it is an index-organized table, which means it is substantially optimized for access by primary key. @@ -267,15 +189,11 @@ with respect to the average number of descendants that an object has, and exponentially with respect to the depth of the context tree. -
- -+
The acs_object_context_index is kept in sync with the
acs_objects
table by triggers like this:
-
+create or replace trigger acs_objects_context_id_in_tr after insert on acs_objects for each row @@ -302,18 +220,13 @@ (:new.object_id, 0, 1); end if; end; -- -+
One final note about
acs_objects. By setting
an object's security_inherit_p column to 'f', you can stop permissions
from cascading down the context tree. In the following example, Joe does not have
the read permissions on C and F.
-
Privileges are also organized hierarchically. In addition to the five main system privileges defined in the ACS Kernel data model, application developers may define their own. Note, however, that this is no longer recommended practice. -
- -+
By defining parent-child relationship between privileges, the OpenACS data model makes it easier for developers to manage permissions. Instead of granting a user explicit @@ -373,24 +276,14 @@ privileges on an object, it is sufficient to grant the user the admin privilege to which the first four privileges are tied. Privileges are structured as follows. -
- -| admin | |||
| create | delete | read | write |
+
| admin | |||
| create | delete | read | write |
Note that admin privileges are
greater than read, write, create and delete privileges combined.
Issuing someone read, write, create and delete privileges will
not result in the person getting
- admin privileges.
The parent-child relationship between privileges is represented in
+ admin privileges.
The parent-child relationship between privileges is represented in
the acs_privilege_hierarchy table:
-
+create table acs_privilege_hierarchy ( privilege not null @@ -401,14 +294,10 @@ constraint acs_privilege_hierarchy_pk primary key (privilege, child_privilege) ); -- -+
As in the case of the context hierarchy, it is convenient to have a flattened representation of this hierarchal structure. This is accomplished by defining the following view. -
- -+create or replace view acs_privilege_descendant_map as select @@ -429,38 +318,23 @@ prior child_privilege = privilege ) or p2.privilege = p1.privilege; -- -+
As the number of different privileges in the system is expected to be reasonably small, there is no pressing need to cache the flattened ansector-descendant view of the privilege hierarchy in a specially maintained table like it is done in the case of the context hierarchy. -
- -Now for the third hierarchy playing a promiment role in the permission system. The party data model is set up as follows. -
- -
create table parties (
party_id
not null
@@ -470,9 +344,7 @@
constraint parties_email_un unique,
url varchar2(200)
);
-
-
- +
create table persons (
person_id
not null
@@ -483,9 +355,7 @@
last_name varchar2(100)
not null
);
-
-
- +
create table users (
user_id
not null
@@ -494,38 +364,30 @@
password char(40),
-- other attributes
);
-
-
- +
create table groups ( group_id not null constraint groups_group_id_fk references parties (party_id) constraint groups_pk primary key, group_name varchar2(100) not null ); -- -
+
Recall that the grantee_id column of the
acs_permissions table references
parties.party_id.
This means that you can grant a privilege on an object to a party, person, user, or group.
Groups represent aggregations of parties. The most common scenario that you are likely
to encounter is a group that is a collection of users, although you could also
have collections of persons, groups, parties, or any mix thereof.
-
+
Given that the most common use of groups is to partition users, how do you
build groups? One way is to grant membership explicitly. If you have
a group named Pranksters, you can assign membership to Pete,
Poly, and Penelope. The fact that these users are members of the
Pranksters group will be recorded in the
membership_rels and acs_rels tables:
-
+create table acs_rels ( rel_id not null @@ -543,9 +405,7 @@ constraint acs_object_rels_un unique (rel_type, object_id_one, object_id_two) ); -- -+create table membership_rels ( rel_id constraint membership_rel_rel_id_fk references acs_rels (rel_id) @@ -555,15 +415,10 @@ constraint membership_rel_mem_ck check (member_state in ('approved', 'banned', 'rejected', 'deleted')) ); -- -+
The acs_rels table entries would look like so: -
- -
+
Read |
|---|
Read acs_rels: right-side is a
subset of left-side, ie
object2 is a part of
object1.
-
+
Another way of building up groups is by adding subgroups. Suppose
we define Merry Pranksters and Sad Pranksters as subgroups
of Pranksters. We say that the Pranksters group
is composed of
groups Merry Pranksters and Sad Pranksters. This
information is stored in the acs_rels
and composition_rels tables.
-
+create table composition_rels ( rel_id constraint composition_rels_rel_id_fk references acs_rels (rel_id) constraint composition_rels_rel_id_pk primary key ); -- -+
The relevant entries in the acs_rels look like so. -
- -
+
+ |
|---|
The composition relationship means that if I add Matt, Mel, and Mary to the Merry Pranksters, they should also automatically become members of the Pranksters group. @@ -650,17 +492,13 @@ G1 is a subgroup of G2, and G2 is a subgroup of G3, then G1 is a subgroup of G3; that is, any member of G1 is also a member of G3. -
- -+
Traversing the group composition hierarchy requires running hierarchical queries, which are expensive in Oracle. As we saw in the Context Hierarchy section, one way of reducing the performance hit incurred by hierarchical queries is to cache query results in a table maintained by triggers. The OpenACS data model defines two such tables: -
- -+create table group_component_index ( group_id not null constraint group_comp_index_group_id_fk @@ -679,9 +517,7 @@ constraint group_component_index_pk primary key (group_id, component_id, rel_id) ) organization index; -- -+create table group_member_index ( group_id not null @@ -698,16 +534,11 @@ constraint group_member_index_pk primary key (member_id, group_id, rel_id) ) organization index; -- -+
The group_component_index table stores a flattened representation of the
group composition hierarchy that is maintained in sync with the acs_rels
and composition_rels tables through triggers.
-
additional comments
-+
additional comments
As far as the group_member_index table goes, I am not sure I understand its
purpose. It maintains group-member relationships that are resolved with respect
to group composition. Note that information stored in
@@ -716,9 +547,7 @@
acs_rels,
and group_component_index. Here
is a view that does it. (This view is not part of the OpenACS Kernel data model.)
-
+create or replace view group_member_view as select @@ -740,15 +569,11 @@ where mr.rel_id = r.rel_id and r.object_id_one = gci.component_id; -- -+
A heuristic way to verify that group_member_view is essentially identical
to group_member_index is to compute the
symmetric difference between the two:
-
+select group_id, member_id from @@ -766,29 +591,18 @@ minus select group_id, member_id from group_member_view ) -- -+
The query returns no rows. The important point is, if we have a flattened view of the composition hierarchy -- like one provided by the group_component_index table -- membership relationship resolution can be computed trivially with no hierarchical queries involved. There is no need to keep the view in a denormalized table, unless doing so results in substantial performance gains. -
- -
Security information is queried by calling the acs_permission.permission_p
function in OpenACS. This is accessible from Tcl via the
permission::permission_p procedure.
-
+create or replace package body acs_permission as -- some stuff removed for the sake of brevity @@ -811,9 +625,7 @@ end; end acs_permission; --problem avoidance
-+
problem avoidance
The function queries
acs_object_party_privilege_map,
which is a humongous view that joins three flattened hierarchies:
@@ -824,22 +636,14 @@
performed by the acs_permission.permission_p
function. Anything other than that would take forever to
finish or would ultimately result in a query error.
-
+
For example, do not try to do things like -
- -+select count(*) from acs_object_party_privilege_map; -- -+
To give another example of things to avoid, I have seen code like this: -
- -+declare cursor cur is select @@ -864,29 +668,20 @@ end; / -- -+
The acs_permission.revoke_permission function merely runs a
delete statement like so:
-
+delete from acs_permissions where object_id = revoke_permission.object_id and grantee_id = revoke_permission.grantee_id and privilege = revoke_permission.privilege; -- -+
Note that in the above example, acs_permissions had only
one entry that needed to be deleted:
-
+
+ |
|---|
The above script would never get around to deleting this entry because it had
to loop through a gazillion rows in the humongous
acs_object_party_privilege_map view.
-
create or replace view acs_object_party_privilege_map as select @@ -931,9 +716,7 @@ privilege from acs_object_grantee_priv_map; -- -
+
create or replace view acs_object_grantee_priv_map as select @@ -945,10 +728,7 @@ acs_privilege_descendant_map m where a.privilege = m.privilege; -- - -
+
create or replace view acs_permissions_all as select @@ -960,9 +740,7 @@ acs_permissions p where op.ancestor_id = p.object_id; -- -
+
create or replace view acs_object_paths as select @@ -971,10 +749,8 @@ n_generations from acs_object_context_index; -+
-- create or replace view group_member_map as select @@ -984,8 +760,4 @@ container_id from group_member_index; -- -