<chapter id="admin.auth">
    <title>Authentication</title>

    <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>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 <link linkend="admin.config.auth.global">Global
	authentication parameters</link> 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>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><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.ldap">
        <title>LDAP and Microsoft Active Directory</title>

        <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 <link linkend="admin.config.auth.ldap">LDAP authentication parameters</link>.</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 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.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.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 <link linkend="admin.auth.standard">standard authentication</link> 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>
