Timeshare security

From PeacockWiki

Contents 1 Overview 2 Auth object 2.1 get_user_id() 2.2 get_user() 2.3 get_user_name() 2.4 static get_auth() 2.5 login($username, $password) 2.6 logout() 2.7 is_authenticated() 2.8 define_user($role_name, $user) 2.9 define_group($role_name, [$group]) 2.10 define_manager($role_name, [$group]) 2.11 define_authenticated([$role_name]) 2.12 define_not_authenticated([$role_name]) 2.13 define_everybody([$role_name]) 2.14 define_admin([$role_name]) 2.15 define_supervisor([$role_name]) 2.16 count_roles() 2.17 can([$role_name]) 2.18 static function auth_error([$error]) 2.19 end_auth([$error]) 3 Notes

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.

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)}