NAME

Security - Security objects and actions in OpenInteract and SPOPS

SYNOPSIS

This document will discuss how security works in both OpenInteract and SPOPS.

BASICS

There are two layers of security in OpenInteract:

Action security
Data security

Action security specifies whether a particular user can generally accomplish a particular task. Data security determines whether the user can perform a particular action on a particular object, or even see the object at all. The distinction between the two is important, because the two are implemented in a unified fashion. This method of implementation is a good thing, but it might be confusing to newcomers.

IMPLEMENTATION

Every SPOPS class can have security implemented by putting the class 'SPOPS::Secure' in the @ISA. Removing security from the class is as simple as removing 'SPOPS::Secure' from the @ISA, but note that doing so will not remove the actual security objects that were previously created.

Setup of database

Here's an idea of how the table for security objects is setup (using MySQL syntax):

 CREATE TABLE security (
  sid        int not null auto_increment,
  object_id  varchar(200) not null,
  class      varchar(20) not null,
  scope      char(1) not null,
  scope_id   varchar(16) not null default 'world',
  level      char(1) not null,
  primary key  ( sid ),
  unique       ( object_id, class, scope, scope_id )
 )

Some notes on this table:

sid
a unique number is necessary for each security object
object_id
represents the unique ID for the object being secured
class
the class of the object being secured, e.g. ('MyApp::User')
scope
w (world) | g (group) | u (user)
scope_id
the ID of the user or group for which the scope holds; the default takes hold when we do not specify a scope_id, which should only be when we specify a scope of 'w'
level
1 (none) | 4 (read) | 8 (write) (actual numbers not final; use the exported constants from the SPOPS::Secure manpage)

We use sid as a primary key but also enforce uniqueness to ensure we do not try to specify two different levels of security for the user or group (or for the whole world) on the same object.

Security as object

Each setting to an object is itself an object. In this manner we can use the SPOPS framework to create/edit/remove security settings. (Note that if you modify the 'SPOPS::Impl::SecurityObj' class to use 'SPOPS::Secure' in its @ISA, you'll probably collapse the Earth in a self-referential object definition cycle. Don't do that.)

The Security object has some extra methods:

fetch_by_obj( $object, \%scope_info )
allows you to fetch all the security settings for an object, or to restrict by any number of users or any number of groups:

 my $sec_obj_class = 'SPOPS::Impl::SecurityObj';
 my \%levels = $sec_obj_class->fetch_by_obj( $msg_obj );
 print "World security: $levels->{world}\n";
 foreach my $gid ( keys %{ $levels->{group} } ) {
   print "Group $gid security: $levels->{group}->{ $gid }\n";
 }
 foreach my $uid ( keys %{ $levels->{user} } ) {
   print "User $uid security: $levels->{user}->{ $uid }\n";
 }

fetch_match( $object, \%scope_info )
See if there are any existing security objects matching the parameters you pass in. Basically, you're saying: ``I have an object and a user, are there any current security settings with these characteristics?'' You're not finding out the security level for that object and scope, but a specific security object.
```
 my $sec_obj = $sec_class->fetch_match( $obj, 
                                        { scope => SEC_SCOPE_USER,
                                          scope_id => $user->id } );
 if ( ! $sec_obj ) { ... }
```

USING SECURITY

Security is interwoven into SPOPS. So when you try to perform any action upon an object, its security is checked. (You need to ensure that you tell SPOPS how to create User and Group objects, and how to retrieve the object mapping to the User performing the current request.)

For instance, when you do a simple fetch on a class that has implemented security:

 my $file = eval { FileClass->fetch( $id ); };

SPOPS first ensures that the current user can READ it before fetching it. It does so by checking the permissions that have been previously set on an object. If the current user has no permissions on the object, SPOPS throws a security error explaining that the current user has no permission to see the requested object. Since this is not a fatal error, your action can continue working but display an error to the user, or whatever you want.

You can check for this as follows:

 my $file = eval { FileClass->fetch( $id ) };
 if ( $@ ) {
    my $ei = SPOPS::Error->get;
    if ( $ei->{type} eq 'security' ) {
        warn "You do not have permission to look at item $id";
    }
    else {
        warn "Error when trying to retrieve item $id: $ei->{system_msg}";
    }
 }

Similarly, if you try to retrieve a group of objects, SPOPS will only return those objects for which the current user has READ (or higher) permission. You can determine which objects the user has WRITE access to by inspecting the object property {tmp_security_level}, which is always set by the fetch() method. For instance:

 my $obj = eval { FileClass->fetch( $id ) };
 if ( $obj->{tmp_security_level} == SEC_LEVEL_READ ) { 
    warn "User has READ access";
 }
 elsif ( $obj->{tmp_security_level} == SEC_LEVEL_WRITE ) { 
    warn "User has WRITE access";
 }

If you try to write (create, update or remove) an object, SPOPS ensures that the current user has permission to do so. Note that while updating or removing an object is fairly simple -- we just check the permissions on the existing item -- creating an object is somewhat more difficult.

Creating an object can be very application specific. For instance, if you're implementing a file explorer program the permission to upload a new file (or create a new file object) depends on the user's permission for the directory object the file is being uploaded to. If the user only has READ permission, then creating a new file is prohibited. However, WRITE permission allows the file to be uploaded properly.

And once the object has been created, what other users/groups should have permission and at what level? Since this is very application-specific, so SPOPS does not impose a particular behavior on your objects. Instead, it allows you to setup default permissions on the class. (See below.)

DEFAULT OBJECT PERMISSIONS

Even though we've covered object security and data security, there remains a little hole.

Each class can have default permissions setup. This should hopefully alleviate the need to create specific security_* handlers for your class. For instance, you can specify that you want all users to be able to create objects of a particular class and each created object will have READ permissions for all groups the user belongs to.

In the future, we will implement a 'Security Policy' which tells the system what you or members of your group should do when creating an object. Currently, the permissions are specified in the SPOPS object configuration file using the 'initial security' key.

AUTHORS

Chris Winters <chris@cwinters.com>

Home | Wiki | OI 1.x Docs | OI 2.x Docs