none

1 files changed, 23 insertions, 18 deletions

diff --git a/TWiki/TWikiUserAuthentication.mdwn b/TWiki/TWikiUserAuthentication.mdwn
index b554fbe1..fe896a91 100644
--- a/TWiki/TWikiUserAuthentication.mdwn
+++ b/TWiki/TWikiUserAuthentication.mdwn
@@ -12,19 +12,27 @@ TWiki uses visitor identification to keep track of who made changes to topics at
 
 ### <a name="Authentication_Options"> Authentication Options </a>
 
-No special installation steps need to be performed if the server is already authenticated. If not, you have three remaining options to controlling user access:
+No special installation steps need to be performed if the server is already authenticated. If not, you have three standard options for controlling user access:
 
-1. **Forget about authentication.** All changes are registered to %MAINWEB%.TWikiGuest user, so you can't tell who made changes. Your site is completely open and public - anyone can browse and edit freely, in classic Wiki mode.<br />
-2. **Use Basic Authentication** for the <code>**edit**</code> and <code>**attach**</code> scripts. This uses .htaccess and generates the familiar grey log-in window. The [[TWikiDocumentation]] has step-by-step instructions.<br />
-3. **Use SSL** to authenticate and secure the whole server.
+1. **Forget about authentication** to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the %MAINWEB%.TWikiGuest default identity, so you can't track individual user activity. <br />
+2. **Use SSL** (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server. <br />
+3. **Use Basic Authentication (HTAccess)** to control access by protecting key scripts: `attach`, `edit=`, `installpasswd`, `password`, `preview`, `rename`, `save`, `upload`, `view`, `viewfile` using .htaccess files. The [[TWikiDocumentation]] has step-by-step instructions.
 
-### <a name="Tracking_by_IP_Address"> Tracking by IP Address </a>
+#### <a name="Partial_Authentication"> Partial Authentication </a>
 
-The <code>**REMOTE\_USER**</code> environment variable is only set for the scripts that are under authentication. If, for example, the <code>**edit**</code>, <code>**save**</code> and <code>**preview**</code> scripts are authenticated, but not <code>**view**</code>, you would get your [[WikiName]] in <code>**preview**</code> for the <code>**%WIKIUSERNAME%**</code> variable, but <code>**view**</code> will show <code>**TWikiGuest**</code> instead of your WikiName.
+**Tracking by IP address** is an experimental feature, enabled in `lib/TWiki.cfg`. It lets you combine open access to some functions, with authentication on others, with full user activity tracking:
 
-There is a way to tell TWiki to remember the user for the scripts that are not authenticated, ex: in case the <code>**REMOTE\_USER**</code> environment variable is not set. TWiki can be configured to remember the IP address/username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non-authenticated scripts like <code>**view**</code> will show the correct username instead of <code>**TWikiGuest**</code>. You can enable this by setting the <code>**$doRememberRemoteUser**</code> flag in <code>**TWiki.cfg**</code>. TWiki persistently stores the IP address/username pairs in the file <code>**$remoteUserFilename**</code>, which is <code>**"$dataDir/remoteusers.txt"**</code> by default. Please note that this can fail if the IP address changes due to dynamically assigned IP addresses or proxy servers.
+* Normally, the <code>**REMOTE\_USER**</code> environment variable is set for the scripts that are under authentication. If, for example, the <code>**edit**</code>, <code>**save**</code> and <code>**preview**</code> scripts are authenticated, but not <code>**view**</code>, you would get your [[WikiName]] in <code>**preview**</code> for the <code>**%WIKIUSERNAME%**</code> variable, but <code>**view**</code> will show <code>**TWikiGuest**</code> instead of your WikiName.
 
-**Authentication Test:** You are %WIKIUSERNAME% (%WIKIUSERNAME%)
+* TWiki can be configured to remember the IP address/username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non-authenticated scripts, like <code>**view**</code>, will show the correct username instead of %MAINWEB%.TWikiGuest.
+
+* Enable this feature by setting the <code>**$doRememberRemoteUser**</code> flag in `TWiki.cfg`. TWiki then persistently stores the IP address/username pairs in the file, `$remoteUserFilename`, which is `"$dataDir/remoteusers.txt"` by default.
+
+* **_NOTE:_** This approach can fail if the IP address changes due to dynamically assigned IP addresses or proxy servers.
+
+**Quick Authentication Test** - Use the %WIKIUSERNAME% variable to return your current identity:
+
+* You are %WIKIUSERNAME%
 
 ### <a name="TWiki_Username_vs_Login_Username"> TWiki Username vs. Login Username </a>
 
@@ -33,19 +41,16 @@ This section applies only if your %WIKITOOLNAME% is installed on a server that i
 %WIKITOOLNAME% internally manages two usernames: Login username and TWiki username.
 
 * **Login username:** When you login to the intranet, you use your existing login username, ex: <code>**pthoeny**</code>. This name is normally passed to %WIKITOOLNAME% by the <code>**REMOTE\_USER**</code> environment variable, and used by internally by %WIKITOOLNAME%. Login usernames are maintained by your system administrator.
+
 * **TWiki username:** Your name in [[WikiNotation]], ex: <code>**PeterThoeny**</code>, is recorded when you register using [[TWikiRegistration]]; doing so also generates a personal home page in the %MAINWEB% web.
 
 %WIKITOOLNAME% can automatically map an intranet username to a TWiki username, provided that the username pair exists in the %MAINWEB%.%WIKIUSERSTOPIC% topic. This is also handled automatically when you register.
 
-> **NOTE:**
->
-> \*To correctly enter a
->
-> 
+> **_NOTE:_**
 >
-> [[WikiName]]
+> **To correctly enter a [[WikiName]]**
 >
-> \* - your own or someone else's - be sure to include the %MAINWEB% web name in front of the Wiki username, followed by a period, and no spaces. Ex:
+> - your own or someone else's - be sure to include the %MAINWEB% web name in front of the Wiki username, followed by a period, and no spaces. Ex:
 >
 > <div>
 >   <center><code><b>%MAINWEB%.<nop>WikiUsername</nop></b></code> or <code><b>%<nop>MAINWEB%.<nop>WikiUsername</nop></nop></b></code></center>
@@ -67,13 +72,13 @@ This section applies only if your %WIKITOOLNAME% is installed on a server that i
 
 ### <a name="Changing_Passwords"> Changing Passwords </a>
 
-Change and reset passwords using forms on regular pages. Use topic-level [[TWikiAccessControl]] to restrict use as required.
+Change and reset passwords using forms on regular pages. Use [[TWikiAccessControl]] to restrict use as required.
 
-* The [[ChangePassword]] form, <code>**TWiki/ChangePassword**</code>:
+* The [[ChangePassword]] form ( <code>**TWiki/ChangePassword**</code> ):
 
 > %INCLUDE\{"ChangePassword"\}%
 
-* The [[ResetPassword]] form <code>**TWiki/ResetPassword**</code>:
+* The [[ResetPassword]] form ( <code>**TWiki/ResetPassword**</code> ):
 
 > %INCLUDE\{"ResetPassword"\}%