- Home
- About
- Testimonials
- Demos
- Download
- Documentation
- Blogs
- Forum
- Support

Packages:
default
System
System.Caching
System.Collections
System.Data
System.Data.ActiveRecord
System.Data.ActiveRecord.Relations
System.Data.ActiveRecord.Scaffold
System.Data.ActiveReecord.Scaffold.InputBuilder
System.Data.Commom.Sqlite
System.Data.Common
System.Data.Common.Mssql
System.Data.Common.Mysql
System.Data.Common.Oracle
System.Data.Common.Pgsql
System.Data.Common.Sqlite
System.Data.DataGateway
System.Data.SqlMap
System.Data.SqlMap.Configuration
System.Data.SqlMap.Statements
System.Exceptions
System.I18N
System.IO
System.Security
System.Util
System.Web
System.Web.Services
System.Web.UI
System.Web.UI.ActiveControls
System.Web.UI.WebControls
System.Web.UI.WebControls.assets
System.Xml
Classes:
IUserManager
TAuthManager
TAuthorizationRule
TAuthorizationRuleCollection
TDbUser
TDbUserManager
TSecurityManager
TSecurityManagerValidationMode
TUser
TUserManager
TUserManagerPasswordMode

Keyword

# Class TAuthManager

    TComponent
       |
       --TApplicationComponent
          |
          --TModule
             |
             --TAuthManager

TAuthManager class

TAuthManager performs user authentication and authorization for a Prado application. TAuthManager works together with a IUserManager module that can be specified via the UserManager property. If an authorization fails, TAuthManager will try to redirect the client browser to a login page that is specified via the LoginPage. To login or logout a user, call login or logout, respectively.

The AuthExpire property can be used to define the time in seconds after which the authentication should expire. AllowAutoLogin specifies if the login information should be stored in a cookie to perform automatic login. Enabling this feature will cause that AuthExpire has no effect since the user will be logged in again on authentication expiration.

To load TAuthManager, configure it in application configuration as follows, <module id="auth" class="System.Security.TAuthManager" UserManager="users" LoginPage="login" /> <module id="users" class="System.Security.TUserManager" />

Since: 3.0
Author: Qiang Xue <qiang.xue@gmail.com>

Method Summary
void | doAuthentication ( mixed $sender, mixed $param) Performs authentication.
void | doAuthorization ( mixed $sender, mixed $param) Performs authorization.
protected string | generateUserKey ()
boolean | getAllowAutoLogin ()
integer | getAuthExpire ()
string | getLoginPage ()
string | getReturnUrl ()
string | getReturnUrlVarName ()
string | getUserKey ()
IUserManager | getUserManager ()
void | init ( TXmlElement $config) Initializes this module.
void | leave ( mixed $sender, mixed $param) Performs login redirect if authorization fails.
boolean | login ( string $username, string $password, integer $expire) Logs in a user with username and password.
void | logout () Logs out a user.
void | onAuthenticate ( mixed $param) Performs the real authentication work.
void | onAuthExpire ( mixed $param) Performs user logout on authentication expiration.
void | onAuthorize ( mixed $param) Performs the real authorization work.
void | setAllowAutoLogin ( boolean $value)
void | setAuthExpire ( integer $value)
void | setLoginPage ( string $pagePath) Sets the login page that the client browser will be redirected to if login is needed.
void | setReturnUrl ( string $value) Sets the URL that the browser should be redirected to when login succeeds.
void | setReturnUrlVarName ( string $value)
void | setUserManager ( string|IUserManager $provider)
boolean | switchUser ( string $username) Switches to a new user.
void | updateSessionUser ( IUser $user) Updates the user data stored in session.

Methods Inherited From TModule
TModule::getID(), TModule::init(), TModule::setID()

Methods Inherited From TApplicationComponent
TApplicationComponent::getApplication(), TApplicationComponent::getRequest(), TApplicationComponent::getResponse(), TApplicationComponent::getService(), TApplicationComponent::getSession(), TApplicationComponent::getUser(), TApplicationComponent::publishAsset(), TApplicationComponent::publishFilePath()

Methods Inherited From TComponent

TComponent::addParsedObject(), TComponent::attachEventHandler(), TComponent::canGetProperty(), TComponent::canSetProperty(), TComponent::createdOnTemplate(), TComponent::detachEventHandler(), TComponent::evaluateExpression(), TComponent::evaluateStatements(), TComponent::getEventHandlers(), TComponent::getSubProperty(), TComponent::hasEvent(), TComponent::hasEventHandler(), TComponent::hasProperty(), TComponent::raiseEvent(), TComponent::setSubProperty(), TComponent::__get(), TComponent::__set()

Constant Summary
string | RETURN_URL_VAR | GET variable name for return url

Method Details

## doAuthentication

public void doAuthentication | (mixed $sender , mixed $param )

Performs authentication.

This is the event handler attached to application's Authentication event. Do not call this method directly.

Input
mixed | $sender | sender of the Authentication event
mixed | $param | event parameter
Output
Exception

## doAuthorization

public void doAuthorization | (mixed $sender , mixed $param )

Performs authorization.

This is the event handler attached to application's Authorization event. Do not call this method directly.

Input
mixed | $sender | sender of the Authorization event
mixed | $param | event parameter
Output
Exception

## generateUserKey

protected string generateUserKey | ()

Output
string | a key used to store user information in session
Exception

## getAllowAutoLogin

public boolean getAllowAutoLogin | ()

Output
boolean | whether to allow remembering login so that the user logs on automatically next time. Defaults to false.
Exception

## getAuthExpire

public integer getAuthExpire | ()

Output
integer | authentication expiration time in seconds. Defaults to zero (no expiration).
Exception

## getLoginPage

public string getLoginPage | ()

Output
string | path of login page should login is required
Exception

## getReturnUrl

public string getReturnUrl | ()

Output
string | URL that the browser should be redirected to when login succeeds.
Exception

## getReturnUrlVarName

public string getReturnUrlVarName | ()

Output
string | the name of the session variable storing return URL. It defaults to 'AppID:ReturnUrl'
Exception

## getUserKey

public string getUserKey | ()

Output
string | a unique variable name for storing user session/cookie data
Exception

## getUserManager

public IUserManager getUserManager | ()

Output
IUserManager | user manager instance
Exception

## init

public void init | (TXmlElement $config )

Initializes this module.

This method is required by the IModule interface.

Input
TXmlElement | $config | configuration for this module, can be null
Output
Exception
throws | TConfigurationException if user manager does not exist or is not IUserManager

## leave

public void leave | (mixed $sender , mixed $param )

Performs login redirect if authorization fails.

This is the event handler attached to application's EndRequest event. Do not call this method directly.

Input
mixed | $sender | sender of the event
mixed | $param | event parameter
Output
Exception

## login

public boolean login | (string $username , string $password , integer $expire )

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.

Input
string | $username | username
string | $password | password
integer | $expire | number of seconds that automatic login will remain effective. If 0, it means user logs out when session ends. This parameter is added since 3.1.1.
Output
boolean | if login is successful
Exception

## logout

public void logout | ()

Logs out a user.

User session will be destroyed after this method is called.

Output
Exception
throws | TConfigurationException if session module is not loaded.

## onAuthenticate

public void onAuthenticate | (mixed $param )

Performs the real authentication work.

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

Input
mixed | $param | parameter to be passed to OnAuthenticate event
Output
Exception
throws | TConfigurationException if session module does not exist.

## onAuthExpire

public void onAuthExpire | (mixed $param )

Performs user logout on authentication expiration.

An 'OnAuthExpire' event will be raised if there is any handler attached to it.

Input
mixed | $param | parameter to be passed to OnAuthExpire event.
Output
Exception

## onAuthorize

public void onAuthorize | (mixed $param )

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.

Input
mixed | $param | parameter to be passed to OnAuthorize event
Output
Exception

## setAllowAutoLogin

public void setAllowAutoLogin | (boolean $value )

Input
boolean | $value | whether to allow remembering login so that the user logs on automatically next time. Users have to enable cookie to make use of this feature.
Output
Exception

## setAuthExpire

public void setAuthExpire | (integer $value )

Input
integer | $value | authentication expiration time in seconds. Defaults to zero (no expiration).
Output
Exception

## setLoginPage

public void setLoginPage | (string $pagePath )

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.

Input
string | $pagePath | path of login page should login is required
Output
Exception

## setReturnUrl

public void setReturnUrl | (string $value )

Sets the URL that the browser should be redirected to when login succeeds.

Input
string | $value | the URL to be redirected to.
Output
Exception

## setReturnUrlVarName

public void setReturnUrlVarName | (string $value )

Input
string | $value | the name of the session variable storing return URL.
Output
Exception

## setUserManager

public void setUserManager | (string|IUserManager $provider )

Input
string|IUserManager | $provider | the user manager module ID or the user manager object
Output
Exception
throws | TInvalidOperationException if the module has been initialized or the user manager object is not IUserManager

## switchUser

public boolean switchUser | (string $username )

Switches to a new user.

This method will logout the current user first and login with a new one (without password.)

Input
string | $username | the new username
Output
boolean | if the switch is successful
Exception

## updateSessionUser

public void updateSessionUser | (IUser $user )

Updates the user data stored in session.

Input
IUser | $user | user object
Output
Exception
throws | new TConfigurationException if session module is not loaded.

Constant Details

### RETURN_URL_VAR

GET variable name for return url

#### Type:

string

#### Value:

'ReturnUrl'