twiki-dev

[<Gre...@nt...>]

Author: GregAbbas
Date: 2005-07-26 09:46:10 -0700 (Tue, 26 Jul 2005)
New Revision: 5925

Added:
   twiki/branches/DEVELOP/data/TWiki/ClientSession.txt
Log:
Item148: missing ClientSession topic

Added: twiki/branches/DEVELOP/data/TWiki/ClientSession.txt
===================================================================
--- twiki/branches/DEVELOP/data/TWiki/ClientSession.txt	2005-07-26 11:55:04 UTC (rev 5924)
+++ twiki/branches/DEVELOP/data/TWiki/ClientSession.txt	2005-07-26 16:46:10 UTC (rev 5925)
@@ -0,0 +1,170 @@
+%META:TOPICINFO{author="GregAbbas" date="1122347578" format="1.1" version="1.2"}%
+%TOC%
+
+---+ Client Session
+
+---++ Description
+
+This is an "in-kernel" version of 
+[[TWiki:Plugins/SessionPlugin][SessionPlugin]] and [[TWiki:Plugins/AuthPagePlugin][AuthPagePlugin]]. (see TWiki:Codev/AddSessionPluginToKernel
+for information about that conversion.)
+
+What this module does is that it encapsulates all of the "conversation memory" within the session. Mostly it keeps track of whether a user is logged in or not (and if so, who they are), but it can keep track of other kinds of state too.
+
+There are two different schemes that you can choose to get authentication information (username and password) from the user, or you can build your own. In the security section of =configure= (or <nop>LocalSite.cfg) specify one of three login managers:
+
+   * none - don't support authentication and don't ever ask the user to log in. This is the default.
+   * TemplateLogin - use a template to ask for a username and password in a web page, and process them using whatever password manager (also in the security section of the configuration page) you choose.
+   * ApacheLogin - use "auth" versions of scripts to encourage your web server (e.g. Apache) to demand credentials from the user.
+
+If you want users to log in, TemplateLogin is the recommended way because it presents a nicer form for asking users for their username and password, and it lets users log out if they want to. ApacheLogin does have a couple of advantages though: it lets you use an Apache authentication module if you want (LDAP, <nop>MySQL, etc) and it can control access to /pub/ if you configure your web server appropriately.
+
+---+++ Force Logons via bin/logon
+
+Any time a user enters a page that needs authentication, they will be forced to log on. However, if you're using ApacheLogin, then if a user never has a need to authenticate, they may never log on and never retrieve their personal settings. It may be convenient to force then to log on.
+
+The ==bin/logon== script accomplishes this. The ==bin/logon== script must be setup in the ==bin/.htaccess== file to be a script which requires a valid user to authenticate. However, once authenticated, it will simply redirect the user to the view URL for the page from which logon was linked.
+
+#StickySkins
+---+++ "Sticky Skins" for All Users, Authenticated or Not
+
+Even if a user is not authenticated, he or she may make the decision that the skin being used should be changed for the current session and the current session only. This could normally be done by passing ==?skin=_skinname_== after every URL, but this is hardly transparent to the user. 
+
+An idea that was implemented in the original version of TWiki:Plugins/SessionPlugin was to create the notion of a "sticky skin" which could be set via a configurable CGI variable (normally ==stickskin==) and would end up setting a session variable SKIN that would be respected over all other SKIN variables. In effect, this session variable would be exactly like passing ==?skin=_skinname_== to every TWiki script.
+
+This same idea is still implemented. The sticky persistent skin is available regardless of whether or not the user has logged in. On top of this, if the sticky skin is set to a configurable value (normally ==default==), the session SKIN will be cleared and let any other SKIN variables take over.
+
+There are a number of %TWIKIWEB%.TWikiVariables below that provide for easy methods to access these sticky skin features. If %<nop>SKINS% is set to be a comma-separated list of skins, the SelectSkin script will give an easy interface to changing skins on the fly and having them stick to the current session. An example of how to link to SelectSkin is given below. SelectSkin itself gives information on its usage as well. Plus, TWiki:Plugins/TigerSkinPlugin and TWiki:Plugins/GnuSkinPlugin both make a use of this SelectSkin page.
+
+#GetSetClearSessionVariables
+---+++ Getting, Setting, and Clearing Session Variables Directly
+
+A TWiki user can get, set, and clear session variables from within TWiki web pages or by using CGI. This allows the user to use the session as a personal "persistent memory space" that is not lost until the web browser is closed. Also note that if a session variable has the same name as a TWiki preference, the session variable's value takes precedence over the TWiki preference. *This allows for per-session preferences.*
+
+To make use of these features, use the tags:
+
+<blockquote>
+%<nop>SESSION_VARIABLE{ *varName* }% %BR%
+%<nop>SESSION_VARIABLE{ *varName*, set="*varValue*" }% %BR%
+%<nop>SESSION_VARIABLE{ *varName*, clear="" }%
+</blockquote>
+
+---+++ Review: Cookies
+
+A common way to pass session information from client to server is by passing per-session cookies (i.e., cookies which are not stored on the user's computer, immediately expire once the browser exits). These cookies will simply hold the unique session identifier.
+
+#TransparentCGISessionID
+---+++ Alternative: Transparent CGI Session ID
+
+If a user disables cookie support in their browser, it won't be possible to rely on cookies to track sessions. In this case, another method is needed to pass session ID information from script to script: by passing a special CGI variable (rather than a cookie) that holds the session ID in it.
+
+Passing the session ID over CGI poses security risks though. If a user copies and pastes a URL that has the session ID in it and sends that URL to another person, that person may get access to the other user's session. If sessions are the only form of authentication verification, this could be catastrophic on an E-Commerce site, for example. So because of the security hazards here, you can decide whether or not to pass session ID information over CGI.
+
+So a transparent interface is provided for this CGI session ID passing. When turned on, if necessary TWiki will change every internal URL it sees to one that also passes session information. This is all done on the fly and requires no additional editing by the TWiki administrator.
+
+#IPMatching
+---+++ IP Matching
+
+As a security feature, TWiki used to allow the administrator to turn on IP matching on sessions. That is, when a client passed a session ID to TWiki, internally it would verify that the client's IP is the same as the IP stamped on the session associated with the session ID passed by the client. This seems like a good idea at first, but after accumulating several years of experience with it we've figured out that actually it causes more problems than it solves. So this feature is no longer available.
+
+#SessionConditionals
+---+++ Conditionals selected with authenticated state of session
+
+Using the operator, %<nop>AUTHENTICATED% it is possible to make pages operate differently after authentication. This may be useful if a login prompt should be supressed (and possibly replaced with a user name) after a user has authenticated. To use it, pass parameters named "then" and/or "else":
+
+<blockquote>
+%<nop>AUTHENTICATED{then="Hello <nop>[<nop>[%<nop>WIKIUSERNAME%][%<nop>SPACEOUT{%<nop>WIKINAME%}%]]!%<nop>BR%%<nop>LOGOUT%" else="%<nop>LOGIN%"}%
+</blockquote>
+
+Which will look like
+
+<blockquote>
+%AUTHENTICATED{then="Hello [[%WIKIUSERNAME%][%SPACEOUT{%WIKINAME%}%]]!%BR%%LOGOUT%" else="%LOGIN%"}%
+</blockquote>
+
+---+++ Technologies used in client session tracking
+
+   * [[http://search.cpan.org/~sherzodr/CGI-Session-3.95//][CGI::Session]] - TWiki highly leverages CGI::Session in order to easily create (by default stored in '/tmp' - this may be configurable in later versions, but seems too much of a security hassle) and manage session information in a clean object-oriented fashion.
+      * CGI::Session knows how to pass cookies to receive session ID information
+      * CGI::Session also by default looks for CGI session ID variables
+      * So the difference between passing session ID via cookie or CGI is transparent
+      * Security is maintained in CGI::Session with its IP_MATCH feature which can be utilized with an option below. With this turned on, sessions will only be accessed if the current client's IP matches the original creator's IP. Otherwise, a new session will be created.
+
+---++ Syntax Rules
+
+There is not much to configure aside from the use of transparent CGI session IDs (see [[#TransparentCGISessionID][above]] for description). Otherwise, these variables just serve to provide information.
+
+   * Information returned from module:
+   | *You type* | *You get* | *If correctly installed* |
+   | %<nop>SESSIONID% | The unique ID for this session | %SESSIONID% |
+   | %<nop>SESSIONVAR% | The CGI and session variable that stores the session ID | %SESSIONVAR% |
+   | %<nop>LOGIN% | Log in link (used by <nop>TigerSkinPlugin) | %LOGIN% |
+   | %<nop>LOGINURL% | URL for forced logon script | %LOGINURL% |
+   | %<nop>LOGOUT% | Log out link | %LOGOUT% |
+   | %<nop>SKINSELECT% | Expects %<nop>SKINS% to have comma-separted list of installed skins. Produces select input to select a "sticky skin" | %SKINSELECT% |
+   | %<nop>SESSION_VARIABLE% | Gets or sets a session variable. | See [[#GetSetClearSessionVariables][above]] for description and example. |
+
+---++ Installation Instructions
+
+   * You need to make sure that your Perl environment includes the CPAN module CGI::Session. If you do not have this it can be installed by running this command =perl -MCPAN -e 'install CGI::Session'= or you can install it manually by downloading the module sources from [[http://search.cpan.org/~sherzodr/CGI-Session-3.95/][CGI-Session at CPAN]] and running =perl Makefile.PL=, =make=, =make test= and =make install=. 
+   * Run [[%SCRIPTURL%/configure%SCRIPTSUFFIX%][configure]] and open the "security setup" section. Make sure =UseClientSessions= is turned on.
+   * If you want to authenticate users (which is generally a good thing), then find =LoginManager= and set it to =TWiki::Client::TemplateLogin= (or =TWiki::Client::ApacheLogin= if you prefer, but that will require some more set-up work, described below). See TWikiUserAuthentication for more information on user authentication.
+
+If you want to use the ApacheLogin module:
+
+   * Change ==bin/.htaccess== so that ==bin/logon== needs a valid-user. In other words, add these lines to ==bin/.htaccess==:%BR%
+<blockquote><blockquote><tt><noautolink><pre>   &lt;Files "logon"&gt;
+          require valid-user
+   &lt;/Files&gt;</pre></noautolink></tt></blockquote></blockquote>
+   * chmod a+x,og-w bin/logon
+   * Test if everything is correctly installed:
+      * See if persistent logons work. This can be done in a number of ways:
+         * Use one of the [[%LOGINURL%][logon]] links above linking to %<nop>LOGINURL%. You should be prompted for username and password and will be returned to this page.
+         * Or logon to TWiki by doing something like attempting to edit this page and cancelling. 
+      * After you've logged on, the following should reflect your username and not the default TWiki user name (i.e. <nop>TWikiGuest):
+         * %<nop>WIKINAME% = <nop>%WIKINAME%
+      * Go to [[%SCRIPTURL%/view%SCRIPTSUFFIX%/%TWIKIWEB%/SelectSkin?fromweb=%WEB%&fromtopic=%TOPIC%][SelectSkin]] to see if "sticky skin" selection works.
+      * Or simply add ==?stickskin=plain== to the end of the URL for this page and see if the skin changes to the plain skin.
+         * If it does, try going to other pages without modifying the URL. The skin should stay plain.
+         * To restore your original skin, add ==?stickskin=default== to a URL.
+      * Verify that the table above under Syntax Rules shows the appropriate data.
+
+
+---++ History
+
+Traditionally, TWiki modes of operation that did not require authentication (like viewing) did not "remember" if a user had already authenticated in a different mode that did require authentication. In other words, if a user logged in, his or her settings would not persist in non-authenticated modes like the viewing mode.
+
+This module provides one strong solution to this problem while also adding a number of other interesting features. It adds the ability to use sessions within TWiki to store information persistently throughout a web browser's visit to a TWiki website. This information will be forgotten after the web browser has been closed, but during the visit it will persist in all modes of operation. This module uses cookies primarily to accomplish this, but also is configured by default to allow for a purely CGI way of doing this as well that does not require cookies.
+
+Note that within TWiki session variables are queried first before a TWiki preference is looked up. This means that if TWiki preferences are "reset" inside the session, the "new" TWiki preference will last throughout the session and will be unique to that particular session. The "sticky skin" features of this module are a simple example of this. Use the get, set, and clear features for control of other types of preferences other than "SKIN."
+
+---+++ Background: Evolution from SessionPlugin
+
+This module is based on version 2.991 (28 Nov 2004) of SessionPlugin.
+
+---+++ Background: Evolution from 1.0 to 2.0
+
+The plugin was a complete rewrite of the 1.000 version of TWiki:Plugins/SessionPlugin. It was meant to replace the functionality of TWiki:Plugins/SessionPlugin and provide an easy way to remember logon information on non-authenticated pages.
+
+After installing that plugin, a user was able to authenticate and carry that authentication information (as well as any other session information other plugins decide to save) around the website, even on pages that do not require authenticated information. 
+
+Conditional features allow different text to be shown to authenticated users than non-authenticated users. This allows for non-authenticated users to be prompted to "logon" and authenticated users to be given links to features tied to themselves, like their TWiki user page.
+
+While the below description is lengthy to give the TWiki administrator as much background as possible, the installation is fairly simple as most of the defaults won't need to be changed except for in very specific cases.
+
+(note that sometimes this plugin is referred to as "SmartSessionPlugin" and other times "SessionPlugin" because it is a rewrite of "SessionPlugin" and must be named "SessionPlugin" to work with TWiki:Codev/BeijingRelease. When installing it, it is forever known as "SessionPlugin". It should only be referred to as "SmartSessionPlugin" in development discussions until TWiki is modified to allow for different session-handling plugin names)
+
+---+++ The Concept of Sessions
+
+This module maintains session information during TWiki visits. The concept of a session became popular with ASP and [[http://www.php.net][PHP]]. A temporary text file is maintained on the server that is associated with an extremely unique identifier. That identifier then is passed from the user's browser in some manner in order to bring into "scope" values which have been stored in that temporary "session" text file.
+
+This not only allows web pages to pass information easily to other web pages on the same web site (i.e., without having to send a complex array of hidden form data back) but also allows for persistent authentication. When a user logs in, a session can be flagged with that user's information and for the remainder of the session the user will stay logged into the site.
+
+__Related Topics:__ %TWIKIWEB%.TWikiPreferences
+
+-- %MAINWEB%.TedPavlic - 24 Aug 2003
+
+-- %MAINWEB%.GregAbbas - 5 Jul 2005
+
+
+


Property changes on: twiki/branches/DEVELOP/data/TWiki/ClientSession.txt
___________________________________________________________________
Name: svn:executable
   + *