Forum OpenACS Development: Best Practices for permissions, straw man

• OpenACS has a fully recursive, granular, etc etc permissions model
• You only get to inherit this for free if you use acs objects
• Even if you do use acs objects, you'll still need to check permissions from time to time
• Before looking at what we do in specific OpenACS packages, I want to get a clear model that is internally consistent. Then we can adjust terminology to match what we use in openacs
• Best Practices has two main parts: a system of privileges (action Y) and permissions (user X can do Y on object Z), and the "rubber-hits-the-road" aspect - that developers need to use the API to test these permissions where appropriate. I am starting with the first part, but I invite people to recommend/point to docs

Starting with one basic permission: "see other peoples' objects". (We could further differentiate between "aware of the existence of objects," "able to enumerate objects," and "see all information about an object" if we wanted to get pedantic.) This is the READ privilege. Someone who has been granted READ on a collection of objects has the "READER" role.

Next step:

• add objects
• see objects you added
• edit an object you added
• delete an object you added

This collection of privs, I propose to call "WRITE". Typically it would be bundled with READ in collection of privs I suggest to call "WRITER." (One could argue that we should only use WRITER to refer to someone with WRITE and nothing else ....)

Next:

• see other people's objects
• edit other people's objects
• delete other people's objects

Lets call this collection of privs EDIT. An EDITOR role includes READ, WRITE, and EDIT.

Next,

• The power to grant READ to other people
• The power to grant WRITE to other people
• The power to grant EDIT to other people

A MODERATOR is, I think, someone with READ, WRITE, EDIT (the power to moderate other people's work), GRANT READ and GRANT WRITE (the power to moderate other people's access).

The last step:

• The power to grant any priv or group of priv, which implies also having all of those privs directly. This we call ADMIN.

References: OpenACS 4.x Permissions Tediously Explained,

Two points: we don't have roles in OpenACS, and privileges don't have fixed meanings.

No Roles: a role is a collection/group of rights that can be granted to a user, currently there is no way to group rights, they have to be granted one by one. Actually this is just done implicitly by each application. When I become a member of the main site, I implicitly can do a number of things. Bug tracker uses roles explicitly. I have used an owner_id in a data model to allow me to select rows. Query-Writer uses membership in a rel_segment to check if a user can assume a role (which is a list of actions on objects).

Privileges have no meaning: You can use the existance of any privilege for any purpose (as a developer).

Dave, a 'role' is not a sub-group, which is essentially what a rel_segment represents. A rel_segment is a group of users which have a defined relationship to a specific group. A group, in OpenACS is a collection of parties. A 'role' is a collection of rights on objects. We don't have an explicit 'role' in OpenACS. If you assign someone to an admin rel_segment of a group, they don't get anything from that. The application has to 'assume' a meaning of that membership type, implicitly creating a role. But there is no data model, no table where roles are defined in OpenACS.

I think workflow has it's own user->role map. My query-writer package uses rel_segments to place users in a role, but the role itself is defined in separate tables, separate from the application.

I see the difference here.

Joel is looking for a way to define which permissions as assigned as a role.

Tom and I have both stated that you can do this yourself, be building an application that grants the permissions to users with a certain relationship to a group, but there is no facility to define several permissions that go together to create a "role".

Joel seems to be advocating openacs sitewide role definitions instead of the current system where each application defines and grants its own permissions.

It is probably best for me to give an example of what I think is the distinction between a role and a privilege (or the sum of a user's privileges).

The easiest example of the difference is that we don't have an explicit 'create' privilege in OpenACS. How can we, privileges apply to objects, and you can't have a privilege on a object before it exists. So the 'create' privilege (which I would call a single element of a role) is usually assumed by the existence of another privilege on another object (or more than one object in some cases). The point is information, which makes up part of a 'role' isn't in a database table, it is implied by the UI.

Another example is the 'update' privilege. Privileges are based on objects. However the UI defines/enforces several roles. Most packages have a 'user' mode and an 'admin' mode, or an admin area. Usually the admin area offers greater access to all the attributes of an object. The admin area may not even check the actual permissions on an object, being able to access this area is enough proof that the user has assumed the admin role on the package.

Don, I'm not suggesting creating roles. I was just pointing out that roles are something that is handled implicitly by the UI. That actually makes roles very flexible. A nice way of assigning a role is to create a rel_segment. You don't even necessarily need to add privileges to the rel_segment, simple membership can be enough to assign a role in certain situations since the UI is doing the work.

My plan for doing this is:

1. Describe a permissions model in sufficient detail that it makes sense and people can tell what I'm talking about
2. Solicit terminology corrections so that my model matches what's already in OpenACS
3. Adjust the recommended permissions model so that's it's a useful default model, including looking at non-OpenACS best practices to avoid re-inventing the wheel
4. As a group, figure out the best way to implement the generic permission system in a new package, including one which uses acs_objects/cr_items, one which doesn't, and one which uses a blend. This task has several parts
   1. Figure out how to get maximum benefit from the toolkit with minimum new code. (Example: If I make the core table of my package an acs_object table, but add no other permission-specific code, how complete a permissions system do I get? What's missing, and how do I put it in? This is tutorial-level stuff)
   2. Figure out best practices for implementing permissions. (Examples: recommend how to set up rel_segs to group privileges, and *which* rel_segs with *which* default names to use to provide the generic model; cull the API for things we should deprecate; etc)

So, I think we're somewhere in step 2. Let me summarize what I think I've heard:

• What I called EDIT, the power to change other people's objects (which includes constitution privs for seeing, changing, and deleting), is currently called WRITE. So where I proposed READ, WRITE, EDIT, we have READ, ??, WRITE.
• A privilege is just a label - it does not have any intrinsic code or refer to any subjects or objects. When a priv is associated with a subject (a party) and an object (an object), the resulting record is called a permission.
• Privs can be bundled together, so that three or four privs can all be assigned or revoked as a group. This is done by creating parent-child relationships between the group priv and the individual privs in acs_privilege_hierarchy. Thus, a priv can be a leaf or a node in a tree, but it's still just a collection of labels. (E.g., "create" could include "create forum," "create message," and "create comment," but that's literally all it is - three names. If a function tries to determine if party X can "create comment" on object Z, and party X can do "create", then party X can also do "create comment.")
• Instead of assigning privs to an invididual person, you can instead assign privs to a group. (I'm less sure on this bit than on the others - please scrutinize.) Group is a node in the party hierarchy, so you can add and remove users and groups of users to groups. You could thus make an "editor" group and a "moderator" group with mostly non-overlapping permissions and put some people in both groups, or even put some people in a "super" group which is in both the "editor" and "moderator" groups.
• An example of everything so far:
  • create a bunch of privs and create a parent priv called "edit"
  • create a group called "Editors" within your new package,
  • make a permission record that says "Editor has priv 'edit' on object '$package_id'"

Before looking at implementation issues, like Tom's point that an "add" priv must apply to a parent object since it can't apply to an object that doesn't exist yet, I want to bang at a few more details in our abstract "best practices" model:

• Do we want to recommend a distinction between "read an object" and "be aware of the existence of an object"? One example is, you can often see subsites listed which you don't have the permission to enter. One solution is that, if you can't read/enter something, you shouldn't be able to see it on lists. The drawback to this is that sometimes you want people to see things so that they see how to ask for access. And sometimes you don't. So I see three choices for best practices:
  • If you don't have "read", you shouldn't see something in lists, and it shouldn't show up in counts
  • If you don't have "read," you can't drill into something, but it's still in lists and counts
  • There are distinct "read" and "see" privs. Showing a list of available subsites hinges on the "see" priv; clicking on that subsite and seeing the contents is requires "read" access (this is an illustrative example, not a suggestion to recode acs_subsite).
• So what's the correct priv tree? My updated straw man:
  • "see own"
  • "read own"
  • "add"
  • "edit own"
  • "delete own"
  • "see other"
  • "read other"
  • "edit other"
  • "delete other"
  • 9 more privs of the form "grant X"
  • "read": "see other" and "read other"
  • "create": "add", "see own", "read own", "edit own", "delete own"
  • "write": "see other", "read other", "edit other", "delete other"
  • "creator": "create" and "read"
  • "editor": "read" and "create" and "write"
  • "grant 'read'"
  • "grant 'create'"
  • "moderator": "editor", "grant 'read'", "grant 'create'"

Your GRANT privs currently are implemented using the single ADMIN privilege, and I personally have never run into the need for greater granularity.  I realize RDBMS security models tend  to provide an extremely granular solution but IMO these also tend to be more complex than we need - and I'd argue more complex than they generally need, too.

Tom's discussion regarding restricting actions on attributes could easily be solved within the permissions system if we made attributes objects.  I'm not suggesting we pay that implementation cost, only that Tom's solution to this problem is made necessary by a compromise in the permissions/object model.

The person who began work on general ratings and I came up with this idea when we started discussing the notion of wanting to be able to say "this party can administer any rating of this type".

The big glitch so far is in permission X, the power to add items and edit and delete the items you have created, and permission Y, the power to edit and delete other people's items. OpenACS calls X "create" and Y "write." I think that "write" is bad in that it doesn't convey the essential difference between X and Y, which is that X applies to your stuff and Y to other people's stuff. My current suggestion is "write" and "edit," but I don't think that's sufficiently better than what we have to merit any refactoring. In fact, it probably makes more sense to just go along with "create" and "write."

And moving forward on step 3: Adjust the recommended permissions model so that's it's a useful default model.

This is my current straw man best practice. By "best practice" I mean a description of how to implement permissions in a typical new OpenACS package, plus code examples. My requirements are:

1. New developers can easily understand it
2. It makes is easy/trivial/automatic to implement common permissions functionality in a new package
3. It is easy to extend to more sophisticated permissions schemes where needed
4. It is easy to handle special cases

The straw man, second draft

In OpenACS, a permission means that a specific user can accomplish a specific function on a specific object. For example, a user #222 can look at a page which contains a list of widgets. Each place in the code that you provide functionality that shouldn't be available to everybody all the time, you need to perform a permissions test. OpenACS uses a standard set of tokens, called "privileges," that are generic enough to apply to most functions.

• For functions that display records or lists of records, test for the "read" privilege.
• For functions that create records, change records, or delete records, test for the "create" privilege.
• For functions that alter or delete records that belong to other people, check for the "write" privilege.
• For functions that grant permissions to other people, check for the "admin" privilege.

This seems very straightforward, until you consider: exactly which object are you testing, how did it get its permissions set, how do you set permissions on objects, and how do you determine which privileges a specific user should have? (notes on assigning privileges to users via groups deferred for a later post)

Let's work through the basic case, a package with a single table of content repository records (see the tutorial for more information). In this package, we need to test for permissions as follows:

• On the index page, which lists all of the records, we do not test for permissions because we want this list to be visible to everyone. If we wanted to restrict access to a specific group, we would grant a permission: permission::grant -party_id 'specific group's id' -object_id 'the package id' -privilege read

  To test this permission, we put the code permission::require_permission -object_id 'the package id' -privilege read at the top of the page. We can omit the party_id, which will then default to the current user id. If we just want to make sure that the viewer is logged in - which implies that they have a valid account - we can skip permissions altogether and just put auth::require_login at the top of the tcl page.

  Note that this is "coarse" permission checking - to show a list of all records in the package, we just check once, at the package level. If we want to list only records which the user has direct "read" access on, we will need (advanced topic goes here, re: both granting and testing per-record, and performance issues).

This is the direction I'm going with the permissions tutorial. Remaining topics are, checking permissions within ad_form (four checks, I think, one each for new_request, edit_request, new_data, and edit_data) and checking permissions on delete. Before I finish it at this level, I'm soliciting feedback.

• Is this how you do it in your packages?
• In a lot of places we don't even use permissions per se but just use acs_object.creation_user as an implicit "admin" priv. This is at least minimally acceptable because we can still hide it within the permission API via via permission::write_permission_p, which returns true if a user has "write" priv or is the creation_user. Do we want to solidify this approach as a best practice? Or push towards explicit priv granting on objects? Or explain a tradeoff?

I would change it like so:

# For functions that display records or lists of records, test for the "read" privilege.
# For functions that create records test for the "create" privilege.
# For functions that alter or delete records check for the "write" privilege. (is there also a delete privilege?)
# For functions that grant permissions to other people, check for the "admin" privilege.

Packages should be explicitly setting permissions on objects. Some packages assign The Public or Registered Users permissions by default. For example, file-storage grants write to Registered Users by default. This could lead to unexpected behavior if a package is mounted under a subsite. It probably should at least default to the application group of the closest subsite (which is equivilant to registered users for the Main Subsite, i believe.)

Packages should be checking for read permission on individual objects. I don't think there is a performance penalty for displaying a reaonable list of objects generated in a single query.

A problem is shown in the search package which effectively runs a permission query for every object which is not efficient enough to use even on a small site.

# For functions that create records, change records, or delete records, test for the "create" privilege.
# For functions that alter or delete records that belong to other people, check for the "write" privilege.

The notion of the permission system is that I can take a party_id, object_id, and permission and check without any additional effort whatsoever.

In your suggested practices, you suggest we check a different permission for the "delete" action depending on whether or not the object "belongs" to the person doing it or not. This breaks a fundamental design element of the permissions system, because you have to check the history of the object then check for one of two permissions. This is a big no-no.

Of course in addition there is already a "delete" permission and we should continue to make use of it, I think, in order to be consistent with existing usage.

Tom, I agree with Dave regarding roles. And I don't see how you end up with a "forums_create" privilege on a photo album. Why would the forums package grant "forums_create" on an album??? How would it even know of the existence of photo-album?

(of course anachronisms like forums_create need to go away, hopefully in 5.1, another of my pet projects that have been on the back burner...)

The workflow case you mention above is, well, workflow.  Fine-grained workflow permissions combined with object state information could implement what you're talking about but Lars chose to do it using roles, I think?  That's how old acs-workflow worked, I haven't looked at the new one, yet.

I guess I don't see your point, though.  I could implement workflow with roles via perms and I challenge you to come up with a role scheme that can't be addressed by combining permissions and workflow.

We don't need to add another mechanism to handle roles ...

I think the answer is that we do have a create privilege, and the trick is that, when you want to create an object, you have to figure out what the "parent" object should be and test for "create" on that object.

Btw, the 'trick' is called 'ad hoc'. It isn't a trick, it just points out the fact that one pemission can be a proxy for others. This is my entire point. Permissions do not have an inherent meaning, but derive meaning by how you use them in the application. You could just as easily require 'write' on the parent object in order to create child objects. But please explain how you are going to handle the case of two different types of child objects. One should be created by one group of users, the other created by a second group of users. Some users can create both. The single 'create' privilege on the parent object is no longer enough. If you, or Don can explain how to do this with permissions, without creating new privileges, please explain.

The permission system doesn't support roles, that is you can look in the database all day long and never figure out what role a user plays, or could play. All this is coded in the UI/application layer. Unfortunately it has limitations if you just use the permissions data model.

Also, you will see the limitation of the permissions model when you consider how users can create or modify objects. It is useful to prohibit users from modifying or setting certain attributes of an object. One create/modify permission cannot control or specify this behavior. To an extent a static UI can help. In OpenACS there are two 'roles' which are statically supported. This is the regular user and the admin user. The admin user has access to the package admin directory, thus allowing greater access to the object attributes. Sometimes the admin functions are placed in the regular user section of the package, but they don't work or even show up unless the user is an admin. These are static roles defined in the application layer. One permission is used as a proxy for greater control over a number of objects and attributes. It is efficient and useful.

The only place I know of where roles are explicitly defined is in the workflow package. And why does it use roles? Because they were necessary to generate a UI dynamically. Whenever you move to a dynamic UI, you must use roles.

Look at it this way: a permission is just data, one tiny piece of data. There isn't a lot of entropy there, so you can't expect it to do too much all by itself. If you have a simple situation, you don't need much entropy. But, to all the scientific types out there, complex systems require more data to represent them. The only question is where is the data going to be stored, and in what format. The permissions data model is unsuited for this in its current form because it requires the existence of the object. Otherwise you have to infer meaning using an ad hoc method from other permissions. As long as you have two roles this works well most of the time when combined with the UI conventions.

Btw, the 'trick' is called 'ad hoc'. It isn't a trick, it just points out the fact that one pemission can be a proxy for others.

How is this different than the write privilege on a Unix directory, which says "you can write this file, and that includes adding a child file or deleting a child file"?

This is my entire point. Permissions do not have an inherent meaning, but derive meaning by how you use them in the application.

Are you suggesting it should? If so, make a solid suggestion. I'm personally comfortable with the fact that it doesn't, because in practice permissions are simple and easy to use and have proven to be both flexible and (with some tweaking on my part) efficient.

You could just as easily require 'write' on the parent object in order to create child objects. But please explain how you are going to handle the case of two different types of child objects. One should be created by one group of users, the other created by a second group of users. Some users can create both. The single 'create' privilege on the parent object is no longer enough. If you, or Don can explain how to do this with permissions, without creating new privileges, please explain.

If you're going to segment content between two user communities like this doesn't it make sense to reflect that in the hierarchical structure of objects you build?

Now ... why a "create"?  It's already there, with proper documentation it should make sense to people, and I can't think of any reason to remove it.  I mean ... this would be a very interesting discussion if we were starting from scratch but we're not.

-carl

If create and write are the same thing, how do we differentiate between permission to change your own objects and permission to change other people's objects?  It seems to me that the way it should work is:  Alice has the create privilege on object #1, and this (is tested for in a UI which ) allows her to create object #2, which is in some sense "inside" object #1.  (Obvious tangent that we've touched on before and which I want to come back to later: is Alice explicitly granted some privileges on object #2?).  Meanwhile, Bob has the write privilege for object #2.  This means that Bob can delete or edit object #2.  It does _not_ mean that Bob can allow other users to delete or edit object #2.

Do I have that example right?