Changeset 3385


Ignore:
Timestamp:
May 25, 2007, 2:21:09 PM (14 years ago)
Author:
Nicklas Nordborg
Message:

References #551. Transferred section about authentication plug-ins from the old format.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/developerdoc/plugin_developer.xml

    r3383 r3385  
    16981698    <sect2 id="plugin_developer.other.authentication">
    16991699      <title>Authentication plug-ins</title>
     1700     
    17001701      <para>
    1701         This documentation is only available in the old format.
    1702         See <ulink url="http://base.thep.lu.se/chrome/site/doc/development/plugins/authentication/index.html"
    1703           >http://base.thep.lu.se/chrome/site/doc/development/plugins/authentication/index.html</ulink>
     1702        BASE provides a plug-in mechanism for authenticating users
     1703        (validating the username and password) when they are logging in.
     1704        This plug-in mechanism is not the same as the regular plug-in API.
     1705        That is, you don't have worry about user interaction or implementing the
     1706        <interfacename>Plugin</interfacename> interface.
    17041707      </para>
     1708     
     1709      <sect3 id="plugin_developer.other.authentication.internal_external">
     1710        <title>Internal vs. external authentation</title>
     1711     
     1712        <para>
     1713          BASE can authenticate users in two ways. Either it uses the internal
     1714          authentiction or the external authentication. With internal
     1715          authentication BASE stores logins and passwords in it's own database.
     1716          With external authentication this is handled by some external
     1717          application. Even with external authentication it is possible to
     1718          let BASE cache the logins/passwords. This makes it possible to login to
     1719          BASE if the external authentication server is down.
     1720        </para>
     1721       
     1722        <note>
     1723          <para>
     1724          An external authentication server can only be used to grant or deny
     1725          a user access to BASE. It can't be used to give a user permissions,
     1726          or put a user into groups or different roles inside BASE.
     1727          </para>
     1728        </note>
     1729
     1730        <para>
     1731          The external authentication service is only used when a user logs in.
     1732          Now, one or more of several things can happen:
     1733         
     1734          <itemizedlist>
     1735          <listitem>
     1736            <para>
     1737              The ROOT user is logging on. Internal authentication is always
     1738              used for the root user and the authenticator plug-in is never
     1739              used.
     1740            </para>
     1741          </listitem>
     1742
     1743          <listitem>
     1744            <para>
     1745              The login is correct and the user is already known to BASE.
     1746              If the plug-in supports extra information (name, email, phone, etc.)
     1747              and the <property>auth.synchronize</property> setting
     1748              is <constant>TRUE</constant> the extra information is copied to
     1749              the BASE server.
     1750            </para>
     1751          </listitem>
     1752         
     1753          <listitem>
     1754            <para>
     1755              The login is correct, but the user isn't known to BASE. This happens
     1756              the first time a user logs in. BASE will create
     1757              a new user account. If the driver supports extra information, it
     1758              is copied to the BASE server (even if <property>auth.synchronize</property>
     1759              isn't set). The new user account will get the default quota
     1760              and be added to the <emphasis>Users</emphasis> role, but not
     1761              to any groups. In the future it may be possible that this is configurable.
     1762            </para>
     1763          </listitem>
     1764
     1765          <listitem>
     1766            <para>
     1767              If password caching is enabled, the password is copied to BASE.
     1768              If an expiration timeout has been set, an expiration date
     1769              will be calculated and set on the user account. The expiration
     1770              date is only checked when the external authentication server is
     1771              down.
     1772            </para>
     1773          </listitem>
     1774
     1775          <listitem>
     1776            <para>
     1777              The authentication server says that the login is invalid or
     1778              the password is incorrect. The user will not be logged in.
     1779              If a user account with the specified login already exists in
     1780              BASE, it will be disabled.
     1781            </para>
     1782          </listitem>
     1783         
     1784          <listitem>
     1785            <para>
     1786              The authentication driver says that something else is wrong.
     1787              If password caching is enabled, internal authentication will be
     1788              used. Otherwise the user will not be logged in. An already
     1789              existing account is not modified or disabled.
     1790            </para>
     1791          </listitem>
     1792          </itemizedlist>
     1793         
     1794          <note>
     1795            <para>
     1796            The <guilabel>Encrypt password</guilabel> option that is
     1797            available on the login page doesn't work with external
     1798            authentication. The simple reason is that the password is
     1799            encrypted with a one-way algorithm making it impossible to
     1800            call <methodname>Authenticator.authenticate()</methodname>.
     1801            </para>
     1802          </note>
     1803         
     1804        </para>
     1805      </sect3>
     1806     
     1807      <sect3 id="plugin_developer.other.authentication.authenticator">
     1808        <title>The Authenticator interface</title>
     1809       
     1810        <para>
     1811          To be able to use external authentication you must create a class
     1812          that implements the
     1813          <interfacename>net.sf.based.core.authentication.Authenticator</interfacename>
     1814          interface. Specify the name of the class in the <property>auth.driver</property>
     1815          setting in <filename>base.config</filename> and
     1816          it's initialisation parameters in the <property>auth.init</property> setting.
     1817        </para>
     1818       
     1819        <para>
     1820          Your class must have a public no-argument constructor. The BASE
     1821          application will create only one instance of the class for lifetime
     1822          of the BASE server. It must be thread-safe since it may be invoked by
     1823          multiple threads at the same time. Here are the methods that you must
     1824          implement
     1825        </para>
     1826       
     1827        <variablelist>
     1828        <varlistentry>
     1829          <term>
     1830            <methodsynopsis language="java">
     1831              <modifier>public</modifier>
     1832              <void/>
     1833              <methodname>init</methodname>
     1834              <methodparam>
     1835                <type>String</type>
     1836                <parameter>settings</parameter>
     1837              </methodparam>
     1838              <exceptionname>AuthenticationException</exceptionname>
     1839            </methodsynopsis>
     1840          </term>
     1841          <listitem>
     1842            <para>
     1843            This method is called just after the object has been created with it's argument
     1844            taken from the <property>auth.init</property> setting in your <filename>base.config</filename>
     1845            file. This method is only called once for an instance of the object. The syntax and meaning of
     1846            the parameter is driver-dependent and should be documented by the plug-in.
     1847            It is irrelevant for the BASE core.
     1848            </para>
     1849          </listitem>
     1850        </varlistentry>
     1851       
     1852        <varlistentry>
     1853          <term>
     1854            <methodsynopsis language="java">
     1855              <modifier>public</modifier>
     1856              <type>boolean</type>
     1857              <methodname>supportsExtraInformation</methodname>
     1858            </methodsynopsis>
     1859          </term>
     1860          <listitem>
     1861            <para>
     1862            This method should simply return <constant>TRUE</constant> or <constant>FALSE</constant>
     1863            depending on if the plug-in supports extra user information or not. The only required
     1864            information about a user is a unique ID and the login. Extra information includes
     1865            name, address, phone, email, etc.
     1866            </para>
     1867          </listitem>       
     1868        </varlistentry>
     1869
     1870        <varlistentry>
     1871          <term>
     1872            <methodsynopsis language="java">
     1873              <modifier>public</modifier>
     1874              <type>AuthenticationInformation</type>
     1875              <methodname>authenticate</methodname>
     1876              <methodparam>
     1877                <type>String</type>
     1878                <parameter>login</parameter>
     1879              </methodparam>
     1880              <methodparam>
     1881                <type>String</type>
     1882                <parameter>password</parameter>
     1883              </methodparam>
     1884              <exceptionname>UnknownLoginException</exceptionname>
     1885              <exceptionname>InvalidPasswordException</exceptionname>
     1886              <exceptionname>AuthenticationException</exceptionname>
     1887            </methodsynopsis>
     1888          </term>
     1889          <listitem>
     1890            <para>
     1891            Try to authenticate a login/password combination. The plug-in should return
     1892            an <classname>AuthenticationInformation</classname> object if the
     1893            authentication is successful or throw an exception if not.
     1894           
     1895            There are three exceptions to choose from:
     1896           
     1897            <itemizedlist>
     1898            <listitem>
     1899              <para>
     1900              <exceptionname>UnknownLoginException</exceptionname>:
     1901              This exception should be thrown if the login is not know to the
     1902              external authentication system.
     1903              </para>
     1904            </listitem>
     1905
     1906            <listitem>
     1907              <para>
     1908              <exceptionname>InvalidPasswordException</exceptionname>:
     1909              This exception should be thrown if the login is known but the
     1910              password is invalid. In case it is considered a security issue
     1911              to reveal that a login exists, the plugin may throw an
     1912              <exceptionname>UnknowLoginException</exceptionname> instead.
     1913              </para>
     1914            </listitem>
     1915           
     1916            <listitem>
     1917              <para>
     1918              <exceptionname>AuthenticationException</exceptionname>:
     1919              In case there is another problem, such as the authentication service
     1920              beeing down. This exception triggers the use of cached passwords
     1921              if caching has been enabled.
     1922              </para>
     1923            </listitem>
     1924            </itemizedlist>
     1925            </para>
     1926          </listitem>       
     1927        </varlistentry>
     1928        </variablelist>
     1929      </sect3>
     1930     
     1931      <sect3 id="plugin_developer.other.authentication.settings">
     1932        <title>Configuration settings</title>
     1933     
     1934        <para>
     1935          The configuration settings for the authentication driver are located
     1936          in the <filename>base.config</filename> file.
     1937          Here is an overview of the settings. For more information read
     1938          <xref linkend="appendix.base.config.authentication" />.
     1939        </para>
     1940       
     1941        <variablelist>
     1942        <varlistentry>
     1943          <term><property>auth.driver</property></term>
     1944          <listitem>
     1945            <para>
     1946            The class name of the authentication plug-in.
     1947            </para>
     1948          </listitem>
     1949        </varlistentry>
     1950
     1951        <varlistentry>
     1952          <term><property>auth.init</property></term>
     1953          <listitem>
     1954            <para>
     1955            Initialisation parameters sent to the plug-in when calling the
     1956            <methodname>Authenticator.init()</methodname> method.
     1957            </para>
     1958          </listitem>
     1959        </varlistentry>
     1960       
     1961        <varlistentry>
     1962          <term><property>auth.synchronize</property></term>
     1963          <listitem>
     1964            <para>
     1965            If extra user information is synchronized at login time or not.
     1966            This setting is ignored if the driver doesn't support extra information.
     1967            </para>
     1968          </listitem>
     1969        </varlistentry>
     1970       
     1971        <varlistentry>
     1972          <term><property>auth.cachepasswords</property></term>
     1973          <listitem>
     1974            <para>
     1975              If passwords should be cached by BASE or not. If the passwords are
     1976              cached a user may login to BASE even if the external authentication
     1977              server is down.
     1978            </para>
     1979          </listitem>
     1980        </varlistentry>
     1981       
     1982        <varlistentry>
     1983          <term><property>auth.daystocache</property></term>
     1984          <listitem>
     1985            <para>
     1986              How many days to cache the passwords if caching has been enabled.
     1987              A value of 0 caches the passwords for ever.     
     1988            </para>
     1989          </listitem>
     1990        </varlistentry>
     1991        </variablelist>
     1992      </sect3>
     1993     
    17051994    </sect2>
    17061995   
Note: See TracChangeset for help on using the changeset viewer.