Permissions provide a way of answering the question, "may the user X perform some action Y on an object Z" ? The CMS permissions are built on top of the acs-permissions package of ACS4; CMS provides extended functionality such as recursive granting of permissions and verifying permission changes.
By default, CMS defines the privilege shown below. Other privileges may be defined by calling acs_privilege.create_privilege and as_privilege.add_child. Privileges are arranged in a hierarchial tree; a privilege includes the capabilities of all of its children.
| Privilege | Pretty Name | Description |
|---|---|---|
| cm_admin | Administrator | Perform any action on any item |
| cm_item_workflow | Modify Workflow | Modify or create item workflow; assign/unassign users to/from workflow tasks. |
| cm_perm_admin | Modify Any Permissions | Modify any permissions on the item for any user; similar to the "owner" concept in UNIX |
| cm_perm | Donate Permissions | Donate own permissions to other users (cannot gain new permissions); revoke own permissions |
| cm_relate | Relate Items | Relate items to this item |
| cm_write | Write | Modify or delete the item |
| cm_new | Create New Item | Create new items with the current item as the parent (useful for content creators) |
| cm_examine | Admin-level Read | View the item in the CMS admin UI |
| cm_read | User-level Read | View the item in the public pages |
A user (the donor) can grant a permission on an item to another user (the recipient) under the following conditions:
The donor has the cm_perm_admin permission on the item
or
The donor has the cm_perm permission on the item as well as the permission he is trying to grant.
A user (the revoker) can revoke a permission an item I to another user (the revokee) under the following conditions:
The revoker has the cm_perm permission on the item and the revokee does not have the cm_perm_admin permission on the item.
or
The revoker has the cm_perm_admin permission on the item and the revokee does not have the cm_admin permission on the item.
The procedures cms_permission.grant_permission and cms_permission.revoke_permission may be used to grant and revoke permissions, optionally modifying permissions on only on the item itself but also on its children. If the conditions above are not satisfied, these functions do nothing. In addition, grant_permission automatically removes all children of the permissions being granted (since the parent permission includes all their capabilities). Similarly, revoke_permission grants all children of the revoked permission in order to make sure that the user does not lose all of his permissions permanently. The parameters to the procedures are as follows:
The item whose permissions are to be changed
The person who is attempting to grant the privilege
The privilege to be granted
The person who will gain the privilege
If 't', applies the operation recursively to all child items of the item (equivalent to UNIX's chmod -r). If 'f', only affects the item itself.
The item whose permissions are to be changed
The person who is attempting to revoke the privilege
The privilege to be revoked
The person who will lose the privilege
If 't', applies the permission change recursively to all child items of the item (equivalent to UNIX's chmod -r). If 'f', only affects the item itself.
The item whose permissions are to be checked
The person whose permissions are to be examined
The privilege to be checked
't' if the user has the specified permission on the item, 'f' otherwise
The above documentation may be out of date; a more up-to-date description of the functions may be obtained using the package documentation browser.
In addition, whenever a new item is created, its creator gains the cm_write and cm_perm permissions on the item, in addition to inheriting all of his permissions from the parent item.
For example, let's say that Alice has the cm_admin permission on a folder "foo". She may perform any action on the folder, and so she chooses to give Bob the cm_new permission on the folder. Bob can now view the folder in the CMS admin UI (since cm_new entails cm_examine), and he can create new items in the folder, but he cannot give himself more permissions on the folder.
Weary with the pressures of administration, Alice decides to remove her cm_admin permission on "foo". She does so, automatically gaining cm_write, cm_item_workflow and cm_perm_admin.
Bob creates a new folder under "foo", called "bar", using his newly-acquired cm_new permission on "foo". He automatically gains cm_write and cm_perm on "bar"; in addition, Alice's pemissions from "foo" are inherited on "bar". Even though Bob has cm_perm on "bar", he cannot revoke any of Alice's permissions, since her cm_perm_admin permission is higher.
When a new content item is created, its context_id in acs_objects is set to the parent_id, and security_inherit_p is set to 't'. This enables the item to inherit the permissions from its parent. In addition, the trigger cr_items_permission_tr assigns the cm_perm and cm_write permissions to the item's creator, unless no creator has been specified.
When permissions are modified for some item, and its security_inherit_p flag is set to 't', permissions from the parent item are copied to the child item, and the security_inherit_p flag is changed to 'f'. This ensures that individual access control lists are maintained for each item.
The grant_permission and revoke_permission procedures ensure that no duplicate permissions exist in the cms_permissions table. That is, if the user is granted a parent privilege, all of its child privileges are removed, since the parent privilege entails all of the child privileges.
The CMS provides a user interface for modifying permissions; the UI is described in more detail in the User Guide.
The simplest way to check if a user has some permission on an item is to query the database directly:
template::query permission_p onevalue "
select cms_permission.permission_p(:item_id, :user_id, :privilege)
from dual"
In addition, CMS provides a Tcl proc check_access, which will verify that the user has a certain permission, and redirect to an error page if the he does not. In addition, check_accesss creates an array called user_permissions in the calling frame. The keys of the array are the privileges, such as cm_admin or cm_examine, and the values are "t" or "f". The syntax for calling the function is as follows:
content::check_access item_id privilege args
where args represents any number of the following switches in any order:
| Switch | Values | Purpose |
|---|---|---|
| -user_id | The id of some user | The user whose permissions are to be checked; the current user will be used by the default. |
| -db | A valid database handle | The database handle to be used in querying; the proc will allocate and release a handle if this switch is not specified. |
| -return_url | Any URL | If the standard error page is shown (which it is by default), provide a link back from the error page to this URL |
| -passthrough | A Tcl list of name-value pairs | Passthrough for the return URL; soon to be deprecated |
| -request-error | none | Indicates that the standard ATS request error should be used for error messages instead of the CMS error page |
| -refresh | none | By default, permissions retreived using check_access are cached persistently. Specify this switch if you wish to refresh the cache from the database. |