Timeshare security

From PeacockWiki

Jump to: navigation, search

Contents

Overview

Page security in timeshare revolves around the Auth object (in lib/auth.php). An instance of this object is available from all smarty HTML (*.smarty) templates in the form of a variable 'user' ($user).

Auth provides login/logout methods, and a facility to define users that should have access to a specific page, and what access they should have.

Auth object

In addition to the following functions, Auth stores a DBDataObject representing the currently logged in user. methods and functions are forwarded to the DBDataObject allowing Auth to act as if it was the DBDataObject. This allows the programmer to easily access the DBDataObject from smarty. This should rarely be required as Auth should handle most needed functions through its own methods.

Note: fields of the DBDataObject may not be accessible until get_user() is called to fetch the object. get_user() is called by most methods of Auth, so chances are it will already have been fetched when required.

Page security is implemented by using a concept of user roles. For each page you may specifiy a number of roles, and which users should fall into those roles. Role name defaults to 'access' (as do all functions with an optional role_name parameter), and access defaults to true. If multiple calls are made for the same role, only one true result is required. (ie. the results are ORed). These properties are true of all the define functions.

get_user_id()

returns the ID of the currently logged in user.

get_user()

returns the DBDataObject representing the currenly logged in user.

get_user_name()

returns the full name of the currently logged in user.

static get_auth()

static function that returns the current instance of Auth.

login($username, $password)

Checks that the username and password match a user in the database, before setting session variables

Returns:

  • 1 - logged in sucessfully
  • -1 - incorrect password
  • -2 - invalid username

logout()

Loggs out the currenly logged in user, removing any session variables

is_authenticated()

returns true if there is a user logged in

define_user($role_name, $user)

Defines that the specified user should have access to the specified role.

define_group($role_name, [$group])

Defines that all students of a group should have access to the specified role. If group is not defined, any student from any group may access the role.

define_manager($role_name, [$group])

Defines that the manager of the specified group should have access to the specified role. If group is not defined, any manager of any group may access the role.

define_authenticated([$role_name])

Defines that all authenticated users may access the role.

define_not_authenticated([$role_name])

Defines that all users who are not authenticated may access the role.

define_everybody([$role_name])

Defines that everyone has access to the specified role.

define_admin([$role_name])

Defines that administrators have access to the role.

define_supervisor([$role_name])

Defines that supervisors have access to the role.

count_roles()

Counts the number of roles the current user has access to. Can be used to determine if the user has any access to the page (if the result>0). Is used in end_auth().

can([$role_name])

Returns true if the current user has access to the specifed role.

static function auth_error([$error])

Creates an authentication error condition. If error is true, an error is thrown, causing the error page to be shown. If error is false, the user is quietly redirected to home.

end_auth([$error])

Checks to see if the current user has any access to the current page. If the user has access to the page, execution continues normally. If the user does not have any access to the page, auth_error() is called, passing the specified error mode.

Example

As mentioned above, the Auth object allows you to define roles within a smarty script. Those roles should reflect actions, such as 'write' 'delete' 'read'. For each role (or action type) you define who has that privelate (which users). If a user access a page that they have no access to, they will be rejected at end_auth, however if a user passes this point (has some access to the page), security must be implemented by the programmer.

This is typically achieved through flow control using the can function as a test. for example

{if $user->can('write')} insert edit box here {/if}

This could be interpreted as "if the user can write to this script, they may be shown the edit box" (where "can" may be expanded to "is allowed to"). This syntax is designed to be as simple as possible so as not to clutter the main body of the smarty script.

Security roles should be defined as a series of define_* functions followed by a end_auth call, all appearing as close to the start of the script as possible (prefereably at the start, but sometimes a database call is required first).

Some sample code will now be explained.

1: {* smarty *}
2: {**:displays a statusreport (either with or without edit links)*}
3: {generate_data_object var="statusreport" query="statusreport" id=$smarty.get.sr}
4: {$user->define_manager('write', $statusreport->get('group'))}
5: {$user->define_group('read', $statusreport->get('group'))}
6: {$user->define_supervisor('comment', $statusreport->get('group'))}
7: {if $statusreport->submitted}{$user->define_supervisor('read')}{/if}
8: {$user->end_auth()}
  1. A standard smarty comment, signifying to the reader this file is processed by the smarty engine
  2. A short comment explaining the purpose of the script (read by generate-file-list.sh)
  3. A call to the database to fetch the requested statusreport (specified by the 'sr' get parameter), and saves it to $statusreport.
  4. Defines that the manager of the group specified should be able to write. The group specified is the group to which the statusreport belongs. In this way, managers from other groups do not have access to the role. See DBDataObject->get()
  5. Defines all members of the speified group have access to the role 'read'.
  6. Defines that the supervisor assigned to the group may comment.
  7. Defines that if $statusreport->submitted is true, all supervisors may read the statusreport. Note this is different (for the purposes of demonstration) to the define_supervisor above, in that it does not have a second parameter. This allows the programmer to set no restrictions about which supervisors, but rather to allow "all" supervisors. This feature is true of many define_* functions.
  8. States that all roles have now been defined. If the user trying to access the page has not recieved any roles, they will be rejected from accessing the page, otherwise execution will continue as normal.

Notes

As it is intended most processing is done in smarty, there is one known disadvantage in the syntax of smarty tags.

 {generate_data_object var="statusreport" query="statusreport" id=$smarty.get.id}
 {$user->define_manager('write', $statusreport->get('group'))}

Smarty does not handle the second '->' (in $statusreport->get('group') ). This is easily solved by a simple workaround. Assign the value to a smarty variable in a seperate command

{generate_data_object var="statusreport" query="statusreport" id=$smarty.get.id}
{assign var="group" value=$statusreport->get('group')}
{$user->define_manager('write', $group)}
Personal tools