NAME

Contentment::Security - Framework for security in Contentment

TODO

This documentation should be moved somewhere else.

DESCRIPTION

This security framework is based closely upon conforming to the restrictions of the SPOPS::Manual::Security framework. That's due to the fact that we general expect plugin modules to use SPOPS for any database back-end. However, the framework is a little more general as it allows for both restricting access to database records (back-end) and restricting access to actual components (front-end).

FRAMEWORK

This is a framework for defining permissions. Permissions must be applied to users and groups, which are defined by another set of security objects. Contentment, as of this writing, provides a single user base implementation, Contentment::Security::DBI.

Administrators and developers using Contentment may write their own implementation to suit their needs, they just need to implement the contract defined here via a Perl module. Then, they need to point the Contentment.conf's security_module variable to the name of that Perl module.

CONTRACT

Your system must do the following:

• Must define two types of objects, groups and users. Users may belong to any number of groups and groups may contain any number of users. The actual definition and relationsihp between these is up to the implementor, so the actual relationships may be as simple or complicated as you, the plugin writer, like.

• The main security module must define two methods: fetch_user and fetch_group. Each should accept an ID value of the object to retrieve as the only argument. Each should return the appropriate user or group object matching the ID.

• The main module should also define two additional methods: fetch_all_users and fetch_all_groups. These should return an array reference containing all users or all groups, respectively.

• The objects returned by fetch_user and fetch_group must return their ID from a function named id.

• The id may be any valid Perl scalar number or string shorter than 256 characters.

• The objects returned by fetch_user must have a method named group, which returns the group objects to which the user belongs in an array reference.

• The objects returned by fetch_group must have a method named user, which returns the user objects which are members of the group in an array reference.

The security module may define any additional methods or functionality it likes. The contract does not specify how users and groups are managed, only how to fetch them.

PERMISSIONS

This security module also provides the definitions of all permissions. There are four types of permissions: object permissions (Contentment::Security::Permission), create permissions (Contentment::Security::CreatePermission), initial object permissions (Contentment::Security::InitialPermission), and URL permissions (Contentment::Security::URLPermissions). These objects are all defined by Contentment::Security.

Object Permissions

There are four object permission security levels that may be associated with any record or group of records: None, Summary, Read, and Write. These permissions are taken directly from Contentment::Manual::Security. None means that the affected user(s) are not able to discover the existence of the matched record(s). Summary means that the affected user(s) are able discovered the matched record(s) but may not be able to read all fields. Read means that he affected user(s) are able to read the matched record(s) in their entirety. Write means that the affected user(s) are able to alter and delete the record as well as read it.

These permissions are matched agains an entire class (table) or against individual records. User permissions are applied first, then group permissions, then other permissions.

Create Permissions

Create permissions are either on or off for groups of users. A Contentlet designer may choose to use these permissions or may define their own by defining a "can_create" method (see Contentment::SPOPS). If a user or group has permission to create a record, the security level is true (non-zero). Otherwise, it will be false (zero).

Matching permissions happens in the same order as object permissions: user, then group, then other.

Initial Permissions

When a user creates a record, we may assign them some initial object permissions. This is what SPOPS calls "Create Permissions," which is confusing to me, so I call them Initial permissions. These are the same set of permissions available for object permissions and the one that matches the user, group, or other user the same way as described in Object Permissions, will be used to assign new permissions added to the Object Permissions table on creation.

This may be superfluous in many cases, but it may be useful if we want to grant the creator special privileges.

URL Permissions

Totally unrelated to the record permissions discussed thus far are the URL permissions. In general, the URL permissions should be avoided if the same restrictions can be achieved through object permissions or create permissions or by developer coded custom permissions. The reason is that URL permissions only block the use of components on the front end of the Contentment system.

This is mostly meant to be useful in cases where access to components cannot be limited on the basis of database records. For example, if a component performs some action just to the file system or some other resource, but doesn't interact with the internal store, these permissions become useful.

ADVANCED USE

The use of any of these permissions directly is considered "advanced." Rather, only Contentlet component designers should regularly need to manipulate these permissions. The permissions system used is really quite complex and shouldn't be exposed to the common user unless necessity forces the issue.