From 97a8c8dbd0c6e107c75c3eaee3633551265e84cb Mon Sep 17 00:00:00 2001 From: xue <> Date: Sun, 20 Nov 2005 15:55:59 +0000 Subject: --- framework/Security/TAuthManager.php | 175 ++++++++++++++++++++++++++++-------- framework/Security/TUserManager.php | 12 +-- 2 files changed, 142 insertions(+), 45 deletions(-) (limited to 'framework/Security') diff --git a/framework/Security/TAuthManager.php b/framework/Security/TAuthManager.php index 32b68cdd..f24a1bdd 100644 --- a/framework/Security/TAuthManager.php +++ b/framework/Security/TAuthManager.php @@ -10,27 +10,55 @@ * @package System.Security */ +/** + * Using TUserManager class + */ +Prado::using('System.Security.TUserManager'); + /** * TAuthManager class * * TAuthManager performs user authentication and authorization for a Prado application. + * TAuthManager works together with a {@link TUserManager} module that can be + * specified via the {@link setUserManager UserManager} property. + * If an authorization fails, TAuthManager will try to redirect the client + * browser to a login page that is specified via the {@link setLoginPage LoginPage}. + * To login or logout a user, call {@link login} or {@link logout}, respectively. * + * To load TAuthManager, configure it in application configuration as follows, + * + * * * @author Qiang Xue * @version $Revision: $ $Date: $ * @package System.Security * @since 3.0 */ - -Prado::using('System.Security.TUserManager'); - class TAuthManager extends TComponent implements IModule { + /** + * GET variable name for return url + */ const RETURN_URL_VAR='ReturnUrl'; + /** + * @var boolean if the module has been initialized + */ private $_initialized=false; + /** + * @var TApplication application instance + */ private $_application; - private $_users=null; + /** + * @var TUserManager user manager instance + */ + private $_userManager=null; + /** + * @var string login page + */ private $_loginPage=null; + /** + * @var boolean whether authorization should be skipped + */ private $_skipAuthorization=false; /** @@ -54,9 +82,20 @@ class TAuthManager extends TComponent implements IModule * This method is required by the IModule interface. * @param TApplication Prado application, can be null * @param TXmlElement configuration for this module, can be null + * @throws TConfigurationException if user manager does not exist or is not TUserManager */ public function init($application,$config) { + if($this->_userManager===null) + throw new TConfigurationException('authmanager_usermanager_required'); + if(is_string($this->_userManager)) + { + if(($users=$application->getModule($this->_userManager))===null) + throw new TConfigurationException('authmanager_usermanager_inexistent',$this->_userManager); + if(!($users instanceof TUserManager)) + throw new TConfigurationException('authmanager_usermanager_invalid',$this->_userManager); + $this->_userManager=$users; + } $this->_application=$application; $application->attachEventHandler('Authentication',array($this,'doAuthentication')); $application->attachEventHandler('EndRequest',array($this,'leave')); @@ -64,36 +103,53 @@ class TAuthManager extends TComponent implements IModule $this->_initialized=true; } + /** + * @return TUserManager user manager instance + */ public function getUserManager() { - if($this->_users instanceof TUserManager) - return $this->_users; - else - { - if(($users=$this->_application->getModule($this->_users))===null) - throw new TConfigurationException('authenticator_usermanager_inexistent',$this->_users); - if(!($users instanceof TUserManager)) - throw new TConfigurationException('authenticator_usermanager_invalid',$this->_users); - $this->_users=$users; - return $users; - } + return $this->_userManager; } + /** + * @param string|TUserManager the user manager module ID or the user mananger object + * @throws TInvalidOperationException if the module has been initialized or the user manager object is not TUserManager + */ public function setUserManager($provider) { - $this->_users=$provider; + if($this->_initialized) + throw new TInvalidOperationException('authmanager_usermanager_unchangeable'); + if(!is_string($provider) && !($provider instanceof TUserManager)) + throw new TConfigurationException('authmanager_usermanager_invalid',$this->_userManager); + $this->_userManager=$provider; } + /** + * @return string path of login page should login is required + */ public function getLoginPage() { return $this->_loginPage; } + /** + * Sets the login page that the client browser will be redirected to if login is needed. + * Login page should be specified in the format of page path. + * @param string path of login page should login is required + * @see TPageService + */ public function setLoginPage($pagePath) { $this->_loginPage=$pagePath; } + /** + * Performs authentication. + * This is the event handler attached to application's Authentication event. + * Do not call this method directly. + * @param mixed sender of the Authentication event + * @param mixed event parameter + */ public function doAuthentication($sender,$param) { $this->onAuthenticate($param); @@ -103,6 +159,13 @@ class TAuthManager extends TComponent implements IModule $this->_skipAuthorization=true; } + /** + * Performs authorization. + * This is the event handler attached to application's Authorization event. + * Do not call this method directly. + * @param mixed sender of the Authorization event + * @param mixed event parameter + */ public function doAuthorization($sender,$param) { if(!$this->_skipAuthorization) @@ -111,6 +174,13 @@ class TAuthManager extends TComponent implements IModule } } + /** + * Performs login redirect if authorization fails. + * This is the event handler attached to application's EndRequest event. + * Do not call this method directly. + * @param mixed sender of the event + * @param mixed event parameter + */ public function leave($sender,$param) { if($this->_application->getResponse()->getStatusCode()===401) @@ -125,6 +195,14 @@ class TAuthManager extends TComponent implements IModule } } + /** + * Performs the real authentication work. + * An Authenticate event will be raised if there is any handler attached to it. + * If the application already has a non-null user, it will return without further authentication. + * Otherwise, user information will be restored from session data. + * @param mixed parameter to be passed to Authenticate event + * @throws TConfigurationException if session module does not exist. + */ public function onAuthenticate($param) { if($this->hasEventHandler('Authenticate')) @@ -133,18 +211,23 @@ class TAuthManager extends TComponent implements IModule return; if(($session=$this->_application->getSession())===null) - throw new TConfigurationException('authenticator_session_required'); + throw new TConfigurationException('authmanager_session_required'); $session->open(); - if(($userManager=$this->getUserManager())===null) - throw new TConfigurationException('authenticator_usermanager_required'); $sessionInfo=$session->getItems()->itemAt($this->generateUserSessionKey()); - $user=$userManager->getUser(null)->loadFromString($sessionInfo); + $user=$this->_userManager->getUser(null)->loadFromString($sessionInfo); $this->_application->setUser($user); } + /** + * Performs the real authorization work. + * Authorization rules obtained from the application will be used to check + * if a user is allowed. If authorization fails, the response status code + * will be set as 401 and the application terminates. + * @param mixed parameter to be passed to Authenticate event + */ public function onAuthorize($param) { - if($this->hasEventHandler('Authenticate')) + if($this->hasEventHandler('Authorize')) $this->raiseEvent('Authorize',$this,$this->_application); if(!$this->_application->getAuthorizationRules()->isUserAllowed($this->_application->getUser(),$this->_application->getRequest()->getRequestType())) { @@ -153,49 +236,63 @@ class TAuthManager extends TComponent implements IModule } } + /** + * @return string a key used to store user information in session + */ protected function generateUserSessionKey() { return md5($this->_application->getUniqueID().'prado:user'); } + /** + * Updates the user data stored in session. + * @param IUser user object + * @throws new TConfigurationException if session module is not loaded. + */ public function updateSessionUser($user) { if(!$user->getIsGuest()) { if(($session=$this->_application->getSession())===null) - throw new TConfigurationException('authenticator_session_required'); + throw new TConfigurationException('authmanager_session_required'); else $session->getItems()->add($this->generateUserSessionKey(),$user->saveToString()); } } + /** + * Logs in a user with username and password. + * The username and password will be used to validate if login is successful. + * If yes, a user object will be created for the application. + * @param string username + * @param string password + * @return boolean if login is successful + */ public function login($username,$password) { - if(($userManager=$this->getUserManager())===null) - throw new TConfigurationException('authenticator_usermanager_required'); - else + if($this->_userManager->validateUser($username,$password)) { - if($userManager->validateUser($username,$password)) - { - $user=$userManager->getUser($username); - $this->updateSessionUser($user); - $this->_application->setUser($user); - return true; - } - else - return false; + $user=$this->_userManager->getUser($username); + $this->updateSessionUser($user); + $this->_application->setUser($user); + return true; } + else + return false; } + /** + * Logs out a user. + * User session will be destroyed after this method is called. + * @throws TConfigurationException if session module is not loaded. + */ public function logout() { - if(($userManager=$this->getUserManager())===null) - throw new TConfigurationException('authenticator_usermanager_required'); - else if(($session=$this->_application->getSession())===null) - throw new TConfigurationException('authenticator_session_required'); + if(($session=$this->_application->getSession())===null) + throw new TConfigurationException('authmanager_session_required'); else { - $userManager->switchToGuest($this->_application->getUser()); + $this->_userManager->switchToGuest($this->_application->getUser()); $session->destroy(); } } diff --git a/framework/Security/TUserManager.php b/framework/Security/TUserManager.php index c4bcbacd..9da386f0 100644 --- a/framework/Security/TUserManager.php +++ b/framework/Security/TUserManager.php @@ -169,12 +169,12 @@ class TUser extends TComponent implements IUser * * TUserManager manages a static list of users {@link TUser}. * The user information is specified via module configuration using the following XML syntax, - * - * - * - * - * - * + * + * + * + * + * + * * * The user passwords may be specified as clear text, SH1 or MD5 hashed by setting * {@link setPasswordMode PasswordMode} as Clear, SH1 or MD5. -- cgit v1.2.3