1.2.x Documentation update for Authentication

Aligning Authentication documentation in 1.2.x with master, following recent
updates.

Updated comment in config_defaults_inc.php about possibility to change
$g_login_method at will, to reflect documentation (and reality).

config_defaults_inc.php

@@ -2502,8 +2502,10 @@
 
 	/**
 	 * login method
-	 * CRYPT or PLAIN or MD5 or LDAP or BASIC_AUTH
-	 * You can simply change this at will. MantisBT will try to figure out how the passwords were encrypted.
+	 * MD5, LDAP, BASIC_AUTH or HTTP_AUTH.
+	 * Note: you may not be able to easily switch encryption methods, so this
+	 * should be carefully chosen at install time. However, MantisBT will attempt
+	 * to "fall back" to older methods if possible.
 	 * @global int $g_login_method
 	 */
 	$g_login_method				= MD5;

docbook/adminguide/en/authentication.sgml

@@ -1,94 +1,66 @@
 <chapter id="admin.auth">
     <title>Authentication</title>
 
-    <para>MantisBT supports several authentication techniques out of the box.  In addition, there is work in progress relating to supporting authentication plug-ins.  Once authentication plug-ins are implemented, then authentication against any protocol or repository of user names and passwords can be done without having to touch MantisBT core code.</para>
+    <para>MantisBT supports several authentication methods out of the box.  In addition, there is work in progress relating to supporting authentication plug-ins.  Once these are implemented, authentication against any protocol or repository of user names and passwords will be possible without having to touch MantisBT core code.</para>
 
-    <para>Although MantisBT supports multiple authentication techniques, it is important to note that MantisBT doesn't yet support hybrid authentication scenarios.  For example, internal staff authentications against LDAP where customer authentications against MantisBT database.</para>
+    <para>It is important to note that MantisBT does not yet support hybrid authentication scenarios.  For example, internal staff authenticating against LDAP while customers authenticate against the MantisBT database with MD5 hash.</para>
+
+    <para>See $g_login_method in <xref linkend="admin.config.auth.global" />
+    for more details about how to configure MantisBT to use one of these
+    authentication techniques.</para>
 
     <section id="admin.auth.standard">
         <title>Standard Authentication</title>
 
-        <para>Standard, or native, authentication is where MantisBT users are authenticated against user records in the MantisBT database.  The passwords are stored in the database in one of several formats:
+        <para>With Standard login method, MantisBT users are authenticated against records in the MantisBT database, where the passwords are stored as a hash.</para>
+        <para>Note: while technically unlimited, the password's length is arbitrarily restricted to 1024 characters (PASSWORD_MAX_SIZE_BEFORE_HASH constant).</para>
+        <para>Values for $g_login_method:
             <itemizedlist>
-                <listitem><para>CRYPT - deprecated.</para></listitem>
-                <listitem><para>CRYPT_FULL_SALT - deprecated.</para></listitem>
-                <listitem><para>PLAIN - deprecated.</para></listitem>
-                <listitem><para>MD5 - This is default and recommended approach.  See <ulink url="http://en.wikipedia.org/wiki/MD5">MD5 topic on Wikipedia</ulink> for more details.</para></listitem>
+                <listitem><para><emphasis><ulink url="http://en.wikipedia.org/wiki/MD5">MD5</ulink></emphasis> is the default - and recommended - method</para></listitem>
+                <listitem><para>Support for additional methods (e.g. <ulink url="http://en.wikipedia.org/wiki/SHA-1">SHA-1</ulink>) could be added in the future</para></listitem>
             </itemizedlist>
         </para>
 
-        <para>See $g_login_methods for more details about how to configure MantisBT to use one of the above authentication techniques.</para>
     </section>
 
-    <section id="admin.auth.http">
-        <title>HTTP_AUTH</title>
+    <section id="admin.auth.ldap">
+        <title>LDAP and Microsoft Active Directory</title>
 
-        <para>When MantisBT is configured to use basic auth, it automatically detects the logged in user and checks if they are already registered in MantisBT, if not, then a new account is automatically created for the username.</para>
+        <para>Value for $g_login_method: <emphasis>LDAP</emphasis></para>
+        <para>Authentication is made against an <ulink url="http://en.wikipedia.org/wiki/LDAP">LDAP</ulink> or <ulink url="http://en.wikipedia.org/wiki/Active_Directory">Active Directory</ulink> server.</para>
+        <para>The LDAP parameters should be setup as explained in <xref linkend="admin.config.auth.ldap" />.</para>
+        <para>An MD5 hash of the user's password will be stored in the database upon successful login, allowing fall-back to Standard Authentication when the LDAP server is not available.</para>
+        <para>The user's ID and password is checked against the Directory; if the credentials are valid, then the user is allowed to login and their user account in MantisBT is created automatically.</para>
     </section>
 
     <section id="admin.auth.basic">
-        <title>BASIC_AUTH</title>
+        <title>Basic Authentication</title>
 
-        <para>TODO</para>
+        <para>Value for $g_login_method: <emphasis>BASIC_AUTH</emphasis></para>
+        <para>When MantisBT is configured to use basic auth, it automatically detects the logged in user and checks if they are already registered in MantisBT, if not, then a new account is automatically created for the username.</para>
+        <para>The password length is limited to the size of the underlying database field (DB_FIELD_SIZE_PASSWORD constant), currently 32 characters.</para>
     </section>
 
-    <section id="admin.auth.ldap">
-        <title>LDAP</title>
-
-        <para>Functionality is provided by using the php-ldap module
-            (/usr/lib/php4/ldap.so). An extra login method is defined within
-            core/user_API.php inside of function is_password_match $f_username,
-            $p_test_password, $p_password ).This has a simple, non encrypted
-            (yet) test of the LDAP directory for that user by asking for an
-            entry with uid=username and password=test_password, if this exists,
-            it is presumed that the user should be granted access.</para>
-            <formalpara>
-                <title>Configuration basics</title>
-                <para>the LDIF format that was tested is as follows:
-                    <programlisting>dn: uid=tests,
-                        dc=test, dc=com, dc=au
-                        department: testdep
-                        organizationname: Testing Organization
-                        cn: Test Smith
-                        assignedgroup: users
-                        givename: Test
-                        sn: Smith
-                        mail: tests@example.com.au
-                        uid: testsuser
-                        Password: password
-                        objectclass: testPerson
-                    </programlisting>
-
-                    The password may be in clear, taken
-                    from the /etc/passwd or /etc/shadow file, or simply encrypted and
-                    added using current LDAP tools.There are some specialized software
-                    for replicating passwd to LDAP and inversely (eg.
-                    <ulink url="http://freshmeat.net/projects/cpu/">http://freshmeat.net/projects/cpu/</ulink>
-                    ).
-                </para>
-            </formalpara>
-
-            <para>Also setup the LDAP parameters explained in the
-                <link linkend="admin.config.auth">Authentication</link>
-                section. Don't forget to change your $g_login_method to
-                LDAP.
-            </para>
+    <section id="admin.auth.http">
+        <title>HTTP Authentication</title>
 
-            <formalpara>
-                <title>Creating new accounts</title><para>There is still a bit of problem when you
-                    want to create a new user to MantisBT using LDAP, you must create the
-                    LDIF entry to LDAP, and also sign up for a new account, if both of
-                    these line up correctly, authentication will proceed.  Email
-                    is queried from the LDAP database if the
-                    authentication is set to use LDAP instead of the user record in the
-                    database entry.</para>
-            </formalpara>
+        <para>Value for $g_login_method: <emphasis>HTTP_AUTH</emphasis></para>
+        <para>TODO</para>
+        <para>The password length is limited to the size of the underlying database field (DB_FIELD_SIZE_PASSWORD constant), currently 32 characters.</para>
+    </section>
 
-        </section>
+    <section id="admin.auth.deprecated">
+        <title>Deprecated authentication methods</title>
 
-        <section id="admin.auth.msad">
-            <title>Microsoft Active Directory</title>
+        <para>The following methods of authentication are deprecated, and supported for backwards-compatibility reasons only.  It is strongly recommended to update MantisBT installations relying on these to use <xref linkend="admin.auth.standard" /> instead.</para>
+        <para>Deprecated values for $g_login_method:
+            <itemizedlist>
+                <listitem><para>CRYPT</para></listitem>
+                <listitem><para>CRYPT_FULL_SALT</para></listitem>
+                <listitem><para>PLAIN</para></listitem>
+            </itemizedlist>
+        With CRYPT-based methods, the password's length is limited as per Standard Authentication. With PLAIN, its size is restricted as for Basic Authentication.
+        </para>
+    </section>
 
-            <para>TODO</para>
-        </section>
 </chapter>