Skip to content

Commit

Permalink
Documentation update following #13163
Browse files Browse the repository at this point in the history 
Updated documentation about the password length limitation.

Modified layout slightly and made it more obvious that some authentication
methods are deprecated; changed some wording.

Updated comment in config_defaults_inc.php about possibility
to change $g_login_method at will, to reflect documentation
(and reality).
  • Loading branch information
@dregad
dregad committed Jul 25, 2011
1 parent 0f9cf06 commit 0993fec
Show file tree
Hide file tree
Showing 3 changed files with 51 additions and 29 deletions.
6 changes: 4 additions & 2 deletions config_defaults_inc.php
View file
Expand Up @@ -1739,8 +1739,10 @@

/**
* Login authentication method. Must be one of
* MD5, LDAP, BASIC_AUTH or HTTP_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;
Expand Down
42 changes: 30 additions & 12 deletions docbook/Admin_Guide/en-US/Authentication.xml
View file
@@ -1,14 +1,14 @@
<?xml version='1.0' encoding='utf-8' ?>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Admin_Guide.ent">
%BOOK_ENTITIES;
]>
<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
Expand All @@ -17,27 +17,31 @@
<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>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>CRYPT - deprecated.</para></listitem>
<listitem><para>CRYPT_FULL_SALT - deprecated.</para></listitem>
<listitem><para>PLAIN - deprecated.</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>

</section>

<section id="admin.auth.http">
<title>HTTP_AUTH</title>
<section id="admin.auth.basic">
<title>Basic Authentication</title>

<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.basic">
<title>BASIC_AUTH</title>
<section id="admin.auth.http">
<title>HTTP Authentication</title>

<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 id="admin.auth.ldap">
Expand Down Expand Up @@ -93,4 +97,18 @@

</section>

<section id="admin.auth.deprecated">
<title>Deprecated authentication methods</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>

</chapter>
32 changes: 17 additions & 15 deletions docbook/Admin_Guide/en-US/Configuration.xml
View file
@@ -1,4 +1,4 @@
<?xml version='1.0' encoding='utf-8' ?>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Admin_Guide.ent">
%BOOK_ENTITIES;
Expand Down Expand Up @@ -1681,32 +1681,34 @@
(defaults to <emphasis>MD5</emphasis>):
<itemizedlist>
<listitem>
<para>MD5 - user's password is stored as
a hash in the database</para>
<para>MD5 - user's password is stored as a hash in the database</para>
</listitem>
<listitem>
<para>LDAP - authenticates against an LDAP
(or Active Directory) server</para>
</listitem>
<listitem>
<para>PLAIN - password is stored in plain,
unencrypted text in the database</para>
<para>LDAP - authenticates against an LDAP (or Active Directory) server</para>
</listitem>
<listitem>
<para>BASIC_AUTH</para>
</listitem>
<listitem>
<para>HTTP_AUTH</para>
</listitem>
</itemizedlist>
In addition, the following deprecated values are supported for backwards-compatibility, and should no longer be used:
<itemizedlist>
<listitem>
<para>PLAIN - password is stored in plain, unencrypted text in the database</para>
</listitem>
<listitem>
<para>CRYPT</para>
</listitem>
<listitem>
<para>CRYPT_FULL_SALT</para>
</listitem>
</itemizedlist></para>

<para>CRYPT and CRYPT_FULL_SALT authentication methods
are deprecated and should not be used.</para>
<para>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.</para>

<para>Note: you will not be able to easily convert
between encryption methods, so this needs to be
carefully chosen at install time. However, MantisBT
will attempt to "fall back" to older methods.</para>
</listitem>
</varlistentry>

Expand Down

0 comments on commit 0993fec

Please sign in to comment.