---+ Package =TWiki::Client=

The package is also a Factory for login managers and also the base class
for all login managers.

On it's own, an object of this class is used when you specify 'none' in
the security setup section of
[[%SCRIPTURL%/configure%SCRIPTSUFFIX%][configure]]. When it is used,
logins are not supported. If you want to authenticate users then you should
consider TemplateLogin or ApacheLogin, which are subclasses of this class.

If you are building a new login manager, then you should write a new subclass
of this class, implementing the methods marked as *VIRTUAL*. There are already
examples in the =lib/TWiki/Client= directory.


%TOC%

---++ StaticMethod *makeClient* <tt>($twiki) -> $TWiki::Client</tt>
Factory method, used to generate a new TWiki::Client object
for the given session.



---++ ObjectMethod *loadSession* <tt>()</tt>

Get the client session data, using the cookie and/or the request URL.
Set up appropriate session variables in the twiki object and return
the login name.



---++ ObjectMethod *checkAccess* <tt>()</tt>
Check if the script being run in this session is authorised for execution.
If not, throw an access control exception.



---++ ObjectMethod *finish* <tt></tt>
Complete processing after the client's HTTP request has been responded
to. Flush the user's session (if any) to disk.



---++ ObjectMethod *userLoggedIn* <tt>($login,$wikiname)</tt>

Called when the user logs in. It's invoked from TWiki::UI::Register::finish
for instance, when the user follows the link in their verification email
message.
	* =$login= - string login name
	* =$wikiname= - string wikiname



---++ ObjectMethod *endRenderingHandler* <tt>()</tt>

This handler is called by getRenderedVersion just before the plugins
postRenderingHandler. So it is passed all HTML text just before it is
printed.



---++ ObjectMethod *addCookie* <tt>($c)</tt>

Add a cookie to the list of cookies for this session.
	* =$c= - a CGI::Cookie



---++ ObjectMethod *modifyHeader* <tt>(\%header)</tt>
Modify a HTTP header
	* =\%header= - header entries



---++ ObjectMethod *redirectCgiQuery* <tt>($url)</tt>
Generate an HTTP redirect on STDOUT, if you can. Return 1 if you did.
Don't forget to pass all query parameters through.
	* =$url= - target of the redirection.



---++ ObjectMethod *getSessionValue* <tt>($name) -> $value</tt>
Get the value of a session variable.



---++ ObjectMethod *setSessionValue* <tt>($name,$value)</tt>
Set the value of a session variable.
We do not allow setting of AUTHUSER.



---++ ObjectMethod *clearSessionValue* <tt>($name)</tt>
Clear the value of a session variable.
We do not allow setting of AUTHUSER.



---++ ObjectMethod *forceAuthentication* <tt>() -> boolean</tt>

*VIRTUAL METHOD* implemented by subclasses

Triggered by an access control violation, this method tests
to see if the current session is authenticated or not. If not,
it does whatever is needed so that the user can log in, and returns 1.

If the user has an existing authenticated session, the function simply drops
though and returns 0.



---++ ObjectMethod *loginUrl* <tt>(...) -> $url</tt>

*VIRTUAL METHOD* implemented by subclasses

Return a full URL suitable for logging in.
	* =...= - url parameters to be added to the URL, in the format required by TWiki::getScriptUrl()



---++ ObjectMethod *loginUrlPath* <tt>() -> $url</tt>

*VIRTUAL METHOD* implemented by subclasses

Get a url path for login (no protocol, host)



---++ ObjectMethod *getUser* <tt>()</tt>

*VIRTUAL METHOD* implemented by subclasses

If there is some other means of getting a username - for example,
Apache has remote_user() - then return it. Otherwise, return undef and
the username stored in the session will be used.



---++ ObjectMethod *checkSession* <tt>()</tt>

Verify that the username we're given matches the session
already stored, and clear the stored session if it doesn't.

If there is another valid username stored in the session,
then someone has somehow just borrowed a session ID from someone
else. To prevent further havoc, clear this session (perhaps
in the future it'd be better just to dispatch a new session ID
to this user; however, if they already have the session ID of
another user, it's probably best to get rid of it since it has
been compromised).

Only makes sense for session managers where there is an alternative source
for a username apart from the stored session (e.g. Apache).


<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the Dev topic instead. -->
