Ignore:
Timestamp:
11/10/08 12:36:51 (4 years ago)
Author:
CrawfordCurrie
Message:

Item109: TWikiUserAuthentication -> UserAuthentication

File:
1 moved

Legend:

Unmodified
Added
Removed

  • trunk/core/data/TWiki/UserAuthentication.txt

    r490 r518  
    11%META:TOPICINFO{author="ProjectContributor" date="1176971123" format="1.0" version="$Rev: 15969 $"}% 
    22%STARTINCLUDE% 
    3 ---+ TWiki User Authentication 
    4  
    5 _TWiki site access control and user activity tracking options_ 
     3---+ User Authentication 
     4 
     5_Controlling who can access your site_ 
    66 
    77%TOC% 
    … …  
    99---++ Overview 
    1010 
    11 Authentication, or "login", is the process by which a user lets TWiki know who they are. 
    12  
    13 Authentication isn't just to do with access control. TWiki uses authentication to identify users, so it can keep track of who made changes, and manage a wide range of personal settings. With authentication enabled, users can personalise TWiki and contribute as recognised individuals, instead of shadows. 
    14  
    15 TWiki authentication is very flexible, and can either stand alone or integrate with existing authentication schemes. You can set up TWiki to require authentication for every access, or only for changes. Authentication is also essential for access control. 
     11Authentication, or "login", is the process by which a user lets %WIKITOOLNAME% know who they are. 
     12 
     13Authentication isn't just to do with [[access control]]. %WIKITOOLNAME% uses authentication to keep track of who made changes, and manage a wide range of personal settings. With authentication enabled, users can personalise %WIKITOOLNAME% and contribute as recognised individuals, instead of shadows. 
     14 
     15%WIKITOOLNAME% authentication is very flexible, and can either stand alone or integrate with existing authentication schemes. You can set up %WIKITOOLNAME% to require authentication for every access, or only for changes. Authentication is also essential for access control. 
    1616 
    1717*Quick Authentication Test* - Use the %<nop>USERINFO% variable to return your current identity: 
    1818   * You are %USERINFO%  
    1919 
    20 TWiki user authentication is split into four sections; password management, user mapping, user registration, and login management. Password management deals with how users personal data is stored. Registration deals with how new users are added to the wiki. Login management deals with how users log in. 
     20%WIKITOOLNAME% user authentication is split into four sections; password management, user mapping, user registration, and login management. Password management deals with how users personal data is stored. Registration deals with how new users are added to the wiki. Login management deals with how users log in. 
    2121 
    2222Once a user is logged on, they can be remembered using a _Client Session_ stored in a cookie in the browser (or by other less elegant means if the user has disabled cookies). This avoids them having to log on again and again. 
    2323 
    24 TWiki user authentication is configured through the Security Settings pane in the [[%SCRIPTURLPATH{"configure"}%][configure]] interface. 
    25  
    26 Please note FileAttachments are not protected by TWiki User Authentication.  
    27  
    28 __%T% Tip:__ TWiki:TWiki.TWikiUserAuthenticationSupplement on TWiki.org has supplemental documentation on user authentication. 
     24%WIKITOOLNAME% user authentication is configured through the Security Settings pane in the [[%SCRIPTURLPATH{"configure"}%][configure]] interface. 
     25 
     26Please note FileAttachments are not protected by %WIKITOOLNAME% User Authentication.  
     27 
     28__%T% Tip:__ NextWiki:Support.UserAuthenticationFAQ on TWiki.org has supplemental documentation on user authentication. 
    2929 
    3030#PasswordManagement 
    3131---++ Password Management 
    3232 
    33 As shipped, TWiki supports the Apache 'htpasswd' password manager. This manager supports the use of =.htpasswd= files on the server. These files can be unique to TWiki, or can be shared with other applications (such as an Apache webserver). A variety of password encodings are supported for flexibility when re-using existing files. See the descriptive comments in the Security Settings section of the [[%SCRIPTURLPATH{"configure"}%][configure]] interface for more details. 
     33As shipped, %WIKITOOLNAME% supports the Apache 'htpasswd' password manager. This manager supports the use of =.htpasswd= files on the server. These files can be unique to %WIKITOOLNAME%, or can be shared with other applications (such as an Apache webserver). A variety of password encodings are supported for flexibility when re-using existing files. See the descriptive comments in the Security Settings section of the [[%SCRIPTURLPATH{"configure"}%][configure]] interface for more details. 
    3434 
    3535You can easily plug in alternate password management modules to support interfaces to other third-party authentication databases. 
     36 
     37The password manager is selected using the {PasswordManager} setting in =configure=. 
    3638 
    3739#UserMapping 
    3840---++ User Mapping 
    3941 
    40 Often when you are using an external authentication method, you want to map from an unfriendly "login name" to a more friendly WikiName. Also, an external authentication database may well have user information you want to import to TWiki, such as user groups. 
    41  
    42 By default, TWiki supports mapping of usernames to wikinames, and supports TWiki groups internal to TWiki. If you want, you can plug in an alternate user mapping module to support import of groups etc. 
     42Usually when you are using an external authentication method, you want to map from an unfriendly "login name" to a more friendly WikiName. Also, an external authentication database may well have user information you want to import to %WIKITOOLNAME%, such as user groups. 
     43 
     44By default, %WIKITOOLNAME% supports mapping of usernames to wikinames, and supports %WIKITOOLNAME% groups internal to %WIKITOOLNAME%. If you want, you can plug in an alternate user mapping module to support import of groups etc. 
     45 
     46The user mapping manager is selected using the {UserMappingManager} setting in =configure=. 
    4347 
    4448#UserRegistration 
    … …  
    4953The registration process is also responsible for creating user topics, and setting up the mapping information used by the User Mapping support. 
    5054 
    51 __%X% Note:__ If you are restricting the entire <nop>%USERSWEB% web to !TWikiGuest, you are required to add !TWikiRegistrationAgent to ALLOWWEBCHANGE in your =%USERSWEB%/WebPreferences=. By doing so, new users are able to register without any errors. 
     55__%X% Note:__ You *must* allow the pseudo-user !TWikiRegistrationAgent to ALLOWWEBCHANGE in your =%USERSWEB%= web. If you block this user, then new users will see errors when they try to register. 
    5256 
    5357#LoginManagement 
    5458---++ Login Management 
    5559 
    56 Login management controls the way users have to log in. There are three basic options; no login, login via a TWiki login page, and login using the webserver authentication support. 
     60Login management controls the way users have to log in. There are three basic options; no login, login via a %WIKITOOLNAME% login page, and login using the webserver authentication support. the login manager is selected using the {LoginManager} setting in =configure=. 
    5761 
    5862#NoLogin 
    59 ---+++ No Login (select =none= in configure) 
     63---+++ No Login (select =none=) 
    6064 
    6165Does exactly what it says on the tin. Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki style. All visitors are given the %USERSWEB%.TWikiGuest default identity, so you can't track individual user activity. 
    … …  
    6468 
    6569#TemplateLogin 
    66 ---+++ Template Login (select =TWiki::LoginManager::TemplateLogin= in configure) 
     70---+++ Template Login (select =TWiki::LoginManager::TemplateLogin=) 
    6771 
    6872Template Login asks for a username and password in a web page, and processes them using whatever Password Manager you choose. Users can log in and log out. Client Sessions are used to remember users. Users can choose to have their session remembered so they will automatically be logged in the next time they start their browser. 
    … …  
    7781   1 Create a new topic to check if authentication works. 
    7882   1 *Edit the %USERSWEB%.TWikiAdminGroup topic in the %USERSWEB% web to include users with system administrator status.* 
    79     <br /> %X% *This is a very important step*, as users in this group can access _all_ topics, independent of TWiki access controls. 
     83    <br /> %X% *This is a very important step*, as users in this group can access _all_ topics, independent of %WIKITOOLNAME% access controls. 
    8084 
    8185TWikiAccessControl has more information on setting up access controls. 
    … …  
    8387%X% At this time TWikiAccessControls cannot control access to files in the =pub= area, unless they are only accessed through the =viewfile= script. If your =pub= directory is set up in the webserver to allow open access you may want to add =.htaccess= files in there to restrict access. 
    8488 
    85 %T% You can create a custom version of the TWikiRegistration form by copying the topic, and then deleting or adding input tags in your copy. The =name=""= parameter of the input tags must start with: ="Twk0..."= (if this is an optional entry), or ="Twk1..."= (if this is a required entry). This ensures that the fields are carried over into the user home page correctly. Do *not* modify the version of TWikiRegistration shipped with TWiki, as your changes will be overwritten next time you upgrade. 
     89%T% You can create a custom version of the TWikiRegistration form by copying the topic, and then deleting or adding input tags in your copy. The =name=""= parameter of the input tags must start with: ="Twk0..."= (if this is an optional entry), or ="Twk1..."= (if this is a required entry). This ensures that the fields are carried over into the user home page correctly. Do *not* modify the version of TWikiRegistration shipped with %WIKITOOLNAME%, as your changes will be overwritten next time you upgrade. 
    8690 
    8791%T% The default new user template page is in [[%SYSTEMWEB%.NewUserTemplate][%SYSTEMWEB%.NewUserTemplate]]. The same variables get expanded as in the [[template topics]]. You can create a custom new user home page by creating the [[%USERSWEB%.NewUserTemplate][%USERSWEB%.NewUserTemplate]] topic, which will then override the default. 
    8892 
    8993#ApacheLogin 
    90 ---+++ Apache Login (select =TWiki::LoginManager::ApacheLogin= in configure) 
    91  
    92 Using this method TWiki does not authenticate users internally. Instead it depends on the =REMOTE_USER= environment variable, which is set when you enable authentication in the webserver. 
     94---+++ Apache Login (select =TWiki::LoginManager::ApacheLogin=) 
     95 
     96Using this method %WIKITOOLNAME% does not authenticate users internally. Instead it depends on the =REMOTE_USER= environment variable, which is set when you enable authentication in the webserver. 
    9397 
    9498The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such as =mod_auth_ldap= or =mod_auth_mysql= you can just plug in directly to them. 
    … …  
    96100The disadvantage is that because the user identity is cached in the browser, you can log in, but you can't log out again unless you restart the browser. 
    97101 
    98 TWiki maps the =REMOTE_USER= that was used to log in to the webserver to a WikiName using the table in %USERSWEB%.TWikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver login name is used for their signature) or register (in which case that login name is mapped to their WikiName). 
    99  
    100 The same private =.htpasswd= file used in TWiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support. 
    101  
    102 *Warning:* Do *not* use the Apache =htpasswd= program with =.htpasswd= files generated by TWiki! =htpasswd= wipes out email addresses that TWiki plants in the info fields of this file. 
     102%WIKITOOLNAME% maps the =REMOTE_USER= that was used to log in to the webserver to a WikiName using the table in %USERSWEB%.TWikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver login name is used for their signature) or register (in which case that login name is mapped to their WikiName). 
     103 
     104The same private =.htpasswd= file used in %WIKITOOLNAME% Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support. 
     105 
     106*Warning:* Do *not* use the Apache =htpasswd= program with =.htpasswd= files generated by %WIKITOOLNAME%! =htpasswd= wipes out email addresses that %WIKITOOLNAME% plants in the info fields of this file. 
    103107 
    104108---++++ Enabling Apache Login using =mod_auth= 
    105109You can use any other Apache authentication module that sets REMOTE_USER. 
    106110   1 Use [[%SCRIPTURLPATH{"configure"}%#LoginManager][configure]] to select the =TWiki::LoginManager::ApacheLogin= login manager. 
    107    1 Use [[%SCRIPTURLPATH{"configure"}%#PasswordManager][configure]] to set up TWiki to create the right kind of =.htpasswd= entries. 
     111   1 Use [[%SCRIPTURLPATH{"configure"}%#PasswordManager][configure]] to set up %WIKITOOLNAME% to create the right kind of =.htpasswd= entries. 
    108112   1 Create a =.htaccess= file in the =twiki/bin= directory.<br />%H% There is an template for this file in =twiki/bin/.htaccess.txt= that you can copy and change. The comments in the file explain what need to be done.<br />%H% If you got it right, the browser should now ask for login name and password when you click on the <u>Edit</u>. If =.htaccess= does not have the desired effect, you may need to "AllowOverride All" for the directory in =httpd.conf= (if you have root access; otherwise, e-mail web server support) 
    109113    <br /> %X% At this time TWikiAccessControls do not control access to files in the =pub= area, unless they are only accessed through the =viewfile= script. If your =pub= directory is set up to allow open access you may want to add =.htaccess= files in there as well to restrict access  
    110    1 You can create a custom version of the TWikiRegistration form by copying the default topic, and then deleting or adding input tags in your copy. The =name=""= parameter of the input tags must start with: ="Twk0..."= (if this is an optional entry), or ="Twk1..."= (if this is a required entry). This ensures that the fields are carried over into the user home page correctly. Do *not* modify the version of TWikiRegistration shipped with TWiki, as your changes will be overwritten next time you upgrade. 
     114   1 You can create a custom version of the TWikiRegistration form by copying the default topic, and then deleting or adding input tags in your copy. The =name=""= parameter of the input tags must start with: ="Twk0..."= (if this is an optional entry), or ="Twk1..."= (if this is a required entry). This ensures that the fields are carried over into the user home page correctly. Do *not* modify the version of TWikiRegistration shipped with %WIKITOOLNAME%, as your changes will be overwritten next time you upgrade. 
    111115    <br />The default new user template page is in [[%SYSTEMWEB%.NewUserTemplate][%SYSTEMWEB%.NewUserTemplate]]. The same variables get expanded as in the [[template topics]]. You can create a custom new user home page by creating the [[%USERSWEB%.NewUserTemplate][%USERSWEB%.NewUserTemplate]] topic, which will then override the default. 
    112116   1 Register yourself in the TWikiRegistration topic. 
    … …  
    114118   1 Create a new topic to check if authentication works. 
    115119   1 *Edit the %USERSWEB%.TWikiAdminGroup topic in the %USERSWEB% web to include users with system administrator status.* 
    116     <br /> %X% *This is a very important step*, as users in this group can access _all_ topics, independent of TWiki access controls. 
     120    <br /> %X% *This is a very important step*, as users in this group can access _all_ topics, independent of %WIKITOOLNAME% access controls. 
    117121TWikiAccessControl has more information on setting up access controls. 
    118122 
    … …  
    126130---++ Sessions 
    127131 
    128 TWiki uses the CPAN:CGI::Session and CPAN:CGI::Cookie modules to track sessions. These modules are de facto standards for session management among Perl programmers. If you can't use Cookies for any reason, CPAN:CGI::Session also supports session tracking using the client IP address. 
    129  
    130 You don't _have_ to enable sessions to support logins in TWiki. However it is *strongly* recommended. TWiki needs some way to remember the fact that you logged in from a particular browser, and it uses sessions to do this. If you don;t enable sessions, TWiki will try hard to remember you, but due to limitations in the browsers it may also forget you (and then suddenly remember you again later!). So for the best user experience, you should enable sessions. 
    131  
    132 There are a number of TWikiVariables available that you can use to interrogate your current session. You can even add your own session variables to the TWiki cookie. Session variables are referred to as "sticky" variables. 
     132%WIKITOOLNAME% uses the CPAN:CGI::Session and CPAN:CGI::Cookie modules to track sessions. These modules are de facto standards for session management among Perl programmers. If you can't use Cookies for any reason, CPAN:CGI::Session also supports session tracking using the client IP address. 
     133 
     134You don't _have_ to enable sessions to support logins in %WIKITOOLNAME%. However it is *strongly* recommended. %WIKITOOLNAME% needs some way to remember the fact that you logged in from a particular browser, and it uses sessions to do this. If you don;t enable sessions, %WIKITOOLNAME% will try hard to remember you, but due to limitations in the browsers it may also forget you (and then suddenly remember you again later!). So for the best user experience, you should enable sessions. 
     135 
     136There are a number of TWikiVariables available that you can use to interrogate your current session. You can even add your own session variables to the %WIKITOOLNAME% cookie. Session variables are referred to as "sticky" variables. 
    133137 
    134138---+++ Getting, Setting, and Clearing Session Variables 
    135139 
    136 You can get, set, and clear session variables from within TWiki web pages or by using script parameters. This allows you 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 variables value takes precedence over the TWiki preference. *This allows for per-session preferences.* 
     140You can get, set, and clear session variables from within %WIKITOOLNAME% web pages or by using script parameters. This allows you 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 %WIKITOOLNAME% preference, the session variables value takes precedence over the %WIKITOOLNAME% preference. *This allows for per-session preferences.* 
    137141 
    138142To make use of these features, use the tags: 
    … …  
    148152---+++ Cookies and Transparent Session IDs 
    149153 
    150 TWiki normally uses cookies to store session information on a client computer. Cookies are a common way to pass session information from client to server. TWiki cookies simply hold a unique session identifier that is used to look up a database of session information on the TWiki server. 
    151  
    152 For a number of reasons, it may not be possible to use cookies. In this case, TWiki has a fallback mechanism; it will automatically rewrite every internal URL it sees on pages being generated to one that also passes session information. 
     154%WIKITOOLNAME% normally uses cookies to store session information on a client computer. Cookies are a common way to pass session information from client to server. %WIKITOOLNAME% cookies simply hold a unique session identifier that is used to look up a database of session information on the %WIKITOOLNAME% server. 
     155 
     156For a number of reasons, it may not be possible to use cookies. In this case, %WIKITOOLNAME% has a fallback mechanism; it will automatically rewrite every internal URL it sees on pages being generated to one that also passes session information. 
    153157 
    154158#UsernameVsLoginName 
    155 ---++ TWiki Username vs. Login Username 
     159---++ Username vs. Login Username 
    156160 
    157161This section applies only if you are using authentication with existing login names (i.e. mapping from login names to WikiNames). 
    … …  
    224228 
    225229%STOPINCLUDE% 
    226 __Related Topics:__ AdminDocumentationCategory, TWikiAccessControl, TWiki:TWiki.TWikiUserAuthenticationSupplement, TWiki:TWiki.SecuringTWikiSite 
     230__Related Topics:__ AdminDocumentationCategory, TWikiAccessControl, TWiki:TWiki.UserAuthenticationSupplement, TWiki:TWiki.SecuringTWikiSite 
Note: See TracChangeset for help on using the changeset viewer.