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" />
Method Summary |
void
|
Performs authentication.
|
void
|
Performs authorization.
|
protected
string
|
|
boolean
|
|
integer
|
|
string
|
|
string
|
|
string
|
|
string
|
|
IUserManager
|
|
void
|
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
|
Logs out a user.
|
void
|
Performs the real authentication work.
|
void
|
Performs user logout on authentication expiration.
|
void
|
Performs the real authorization work.
|
void
|
|
void
|
|
void
|
Sets the login page that the client browser will be redirected to if login is needed.
|
void
|
Sets the URL that the browser should be redirected to when login succeeds.
|
void
|
|
void
|
|
boolean
|
Switches to a new user.
|
void
|
Updates the user data stored in session.
|
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
|
init
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
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
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. |
|