Timeshare security - Revision history

Trevorp: /* Philosophy */

Trevorp — Thu, 22 Sep 2005 02:45:05 GMT

Philosophy

←Older revision		Revision as of 02:45, 22 September 2005
Line 55:		Line 55:
	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.		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.

-	==Philosophy==	+	==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.		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.

Line 64:		Line 64:
	This syntax is designed to be as simple as possible so as not to clutter the main body of the smarty script.		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()}
		+	# A standard smarty comment, signifying to the reader this file is processed by the smarty engine
		+	# A short comment explaining the purpose of the script (read by generate-file-list.sh)
		+	# A call to the database to fetch the requested statusreport (specified by the 'sr' get parameter), and saves it to $statusreport.
		+	# 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 [[Smarty_db#DBDataObject-.3Eget.28.24nm.29 \|DBDataObject->get()]]
		+	# Defines all members of the speified group have access to the role 'read'.
		+	# Defines that the supervisor assigned to the group may comment.
		+	# 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.
		+	# 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==		==Notes==

Trevorp at 02:25, 22 September 2005

Trevorp — Thu, 22 Sep 2005 02:25:04 GMT

←Older revision		Revision as of 02:25, 22 September 2005
Line 54:		Line 54:
	===end_auth([$error])===		===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.		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.
		+
		+	==Philosophy==
		+	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.
		+
		+
		+

	==Notes==		==Notes==

Trevorp: /* Auth object */

Trevorp — Tue, 20 Sep 2005 12:28:09 GMT

Auth object

←Older revision		Revision as of 12:28, 20 September 2005
Line 9:		Line 9:
	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.		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.	+	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()===		===get_user_id()===
Line 30:		Line 30:
	===is_authenticated()===		===is_authenticated()===
	returns true if there is a user logged in		returns true if there is a user logged in
-	===define([[$role_name], $access])===
-	Defines a role, and if the current user should have access to it. 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, only one true $access is required. (ie. the results are ORed). These properties are true of all the define functions.
	===define_user($role_name, $user)===		===define_user($role_name, $user)===
	Defines that the specified user should have access to the specified role.		Defines that the specified user should have access to the specified role.

Trevorp: /* Auth object */

Trevorp — Tue, 20 Sep 2005 12:18:51 GMT

Auth object

←Older revision		Revision as of 12:18, 20 September 2005
Line 8:		Line 8:

	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.		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.

	===get_user_id()===		===get_user_id()===
Line 29:		Line 31:
	returns true if there is a user logged in		returns true if there is a user logged in
	===define([[$role_name], $access])===		===define([[$role_name], $access])===
-	'access'true	+	Defines a role, and if the current user should have access to it. 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, only one true $access is required. (ie. the results are ORed). These properties are true of all the define functions.
-	add a user to a role	+
	===define_user($role_name, $user)===		===define_user($role_name, $user)===
-	add a user to a role if they are the required user	+	Defines that the specified user should have access to the specified role.
	===define_group($role_name, [$group])===		===define_group($role_name, [$group])===
-	add a user to a role if they are in the required 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])===		===define_manager($role_name, [$group])===
-	add user to a role if they manage the specified 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])===		===define_authenticated([$role_name])===
		+	Defines that all authenticated users may access the role.
	===define_not_authenticated([$role_name])===		===define_not_authenticated([$role_name])===
		+	Defines that all users who are not authenticated may access the role.
	===define_everybody([$role_name])===		===define_everybody([$role_name])===
		+	Defines that everyone has access to the specified role.
	===define_admin([$role_name])===		===define_admin([$role_name])===
		+	Defines that administrators have access to the role.
	===define_supervisor([$role_name])===		===define_supervisor([$role_name])===
		+	Defines that supervisors have access to the role.
	===count_roles()===		===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])===		===can([$role_name])===
		+	Returns true if the current user has access to the specifed role.
	===static function auth_error([$error])===		===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])===		===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==		==Notes==

Trevorp: /* Auth object */

Trevorp — Tue, 20 Sep 2005 11:44:45 GMT

Auth object

←Older revision		Revision as of 11:44, 20 September 2005
Line 20:		Line 20:
	Checks that the username and password match a user in the database, before setting session variables		Checks that the username and password match a user in the database, before setting session variables

-	returns	+	Returns:
-	*1 - logged in sucessfully	+	* 1 - logged in sucessfully
	*-1 - incorrect password		*-1 - incorrect password
	*-2 - invalid username		*-2 - invalid username
	===logout()===		===logout()===
		+	Loggs out the currenly logged in user, removing any session variables
	===is_authenticated()===		===is_authenticated()===
		+	returns true if there is a user logged in
	===define([[$role_name], $access])===		===define([[$role_name], $access])===
	'access'true		'access'true

Trevorp: /* Auth object */

Trevorp — Tue, 20 Sep 2005 11:42:19 GMT

Auth object

←Older revision		Revision as of 11:42, 20 September 2005
Line 6:		Line 6:
	==Auth object==		==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.		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.

	===get_user_id()===		===get_user_id()===
		+	returns the ID of the currently logged in user.
	===get_user()===		===get_user()===
		+	returns the DBDataObject representing the currenly logged in user.
	===get_user_name()===		===get_user_name()===
-	===static function get_auth()===	+	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)===		===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()===		===logout()===
	===is_authenticated()===		===is_authenticated()===
Line 32:		Line 44:
	===static function auth_error([$error])===		===static function auth_error([$error])===
	===end_auth([$error])===		===end_auth([$error])===
-

	==Notes==		==Notes==

Trevorp at 11:35, 20 September 2005

Trevorp — Tue, 20 Sep 2005 11:35:11 GMT

←Older revision		Revision as of 11:35, 20 September 2005
Line 11:		Line 11:
	===get_user_name()===		===get_user_name()===
	===static function get_auth()===		===static function get_auth()===
-	===__get($name)===
-	===__set($nm, $val)===
-	===__call($n, $p)===
	===login($username, $password)===		===login($username, $password)===
	===logout()===		===logout()===
	===is_authenticated()===		===is_authenticated()===
-	===define($role_name = 'access', $access = true)===	+	===define([[$role_name], $access])===
		+	'access'true
	add a user to a role		add a user to a role
	===define_user($role_name, $user)===		===define_user($role_name, $user)===
	add a user to a role if they are the required user		add a user to a role if they are the required user
-	===define_group($role_name, $group = null)===	+	===define_group($role_name, [$group])===
	add a user to a role if they are in the required group		add a user to a role if they are in the required group
-	===define_manager($role_name, $group = '%')===	+	===define_manager($role_name, [$group])===
	add user to a role if they manage the specified group		add user to a role if they manage the specified group
-	===define_authenticated($role_name = 'access')===	+	===define_authenticated([$role_name])===
-	===define_not_authenticated($role_name = 'access')===	+	===define_not_authenticated([$role_name])===
-	===define_everybody($role_name = 'access')===	+	===define_everybody([$role_name])===
-	===define_admin($role_name = 'access')===	+	===define_admin([$role_name])===
-	===define_supervisor($role_name = 'access')===	+	===define_supervisor([$role_name])===
	===count_roles()===		===count_roles()===
-	===can($role = null)===	+	===can([$role_name])===
-	===static function auth_error($error = true)===	+	===static function auth_error([$error])===
-	===end_auth($error = true)===	+	===end_auth([$error])===

Trevorp at 11:33, 20 September 2005

Trevorp — Tue, 20 Sep 2005 11:33:08 GMT

←Older revision		Revision as of 11:33, 20 September 2005
Line 1:		Line 1:
	==Overview==		==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).		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.
		+
		+	===get_user_id()===
		+	===get_user()===
		+	===get_user_name()===
		+	===static function get_auth()===
		+	===__get($name)===
		+	===__set($nm, $val)===
		+	===__call($n, $p)===
		+	===login($username, $password)===
		+	===logout()===
		+	===is_authenticated()===
		+	===define($role_name = 'access', $access = true)===
		+	add a user to a role
		+	===define_user($role_name, $user)===
		+	add a user to a role if they are the required user
		+	===define_group($role_name, $group = null)===
		+	add a user to a role if they are in the required group
		+	===define_manager($role_name, $group = '%')===
		+	add user to a role if they manage the specified group
		+	===define_authenticated($role_name = 'access')===
		+	===define_not_authenticated($role_name = 'access')===
		+	===define_everybody($role_name = 'access')===
		+	===define_admin($role_name = 'access')===
		+	===define_supervisor($role_name = 'access')===
		+	===count_roles()===
		+	===can($role = null)===
		+	===static function auth_error($error = true)===
		+	===end_auth($error = true)===
		+

	==Notes==		==Notes==

Trevorp at 11:23, 20 September 2005

Trevorp — Tue, 20 Sep 2005 11:23:37 GMT

New page

==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).

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