Changeset 3385
- Timestamp:
- May 25, 2007, 2:21:09 PM (14 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/developerdoc/plugin_developer.xml
r3383 r3385 1698 1698 <sect2 id="plugin_developer.other.authentication"> 1699 1699 <title>Authentication plug-ins</title> 1700 1700 1701 <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. 1704 1707 </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 1705 1994 </sect2> 1706 1995
Note: See TracChangeset
for help on using the changeset viewer.
