Changeset 2977


Ignore:
Timestamp:
Nov 29, 2006, 2:50:51 PM (16 years ago)
Author:
Nicklas Nordborg
Message:

Fixes #138: Write documentation: 5c) Authentication plug-ins

Location:
trunk/doc
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/admin/base.config.html

    r2966 r2977  
    2727<html>
    2828  <head>
    29     <title>BASE 2.0 - Administrator documentation: base.config reference</title>
     29    <title>BASE 2 - Administrator documentation: base.config reference</title>
    3030  <link rel=stylesheet type="text/css" href="../styles.css">
    3131  </head>
    … …  
    3333
    3434<div class="navigation">
    35   <a href="../index.html">BASE</a>
     35  <a href="../index.html">BASE 2</a>
    3636  <img src="../next.gif">
    3737  <a href="index.html">Administrator documentation</a>
    … …  
    4040</div>
    4141
    42 <h1>BASE 2.0 - Administrator documentation: base.config reference</h1>
     42<h1>BASE 2 - Administrator documentation: base.config reference</h1>
    4343
    4444<div class="abstract">
    … …  
    187187  </dl>
    188188
    189   <a name="secondary"></a>
     189  <a name="authentication"></a>
    190190  <h2>2. Authentication section</h2>
    191191
    192   TODO
    193 
     192  <p>
     193    Settings related to external authentication. For more information
     194    see: <a href="../development/plugins/authentication/index.html"
     195      >Development information - Plugins for user authentication</a>
     196  </p>
     197 
     198  <dl>
     199  <dt class="method">auth.driver</dt>
     200  <dd>
     201    The class name of the plugin that acts as the authentication driver. BASE ships
     202    with a simple plugin that checks if a user has a valid email account on a POP3
     203    server. It is not enabled by default. The class name of that plugin is
     204    <code>net.sf.basedb.core.authentication.POP3Authenticator</code>. If no class
     205    is specified internal authentication is used.
     206  </dd>
     207 
     208  <dt class="method">auth.init</dt>
     209  <dd>
     210    Initialisation paramters sent to the plugin by calling the
     211    <code>init()</code> method. The syntax and meaning of this string
     212    depends on the plugin. For the <code>POP3Authenticator</code> this is simply
     213    the IP-address of the mail server.
     214  </dd>
     215 
     216  <dt class="method">auth.synchronize</dt>
     217  <dd>
     218    If this setting is 1 or TRUE the BASE core will synchronize the extra
     219    information (name, address, email, etc.) sent by the authentication driver
     220    when a user logs in to BASE. This setting is ignored if the driver doesn't
     221    support extra information. The <code>POP3Authenticator</code> returns FALSE.
     222  </dd>
     223 
     224  <dt class="method">auth.cachepasswords</dt>
     225  <dd>
     226    If passwords should be cached by BASE or not. If the passwords are cached a user
     227    may login to BASE even if the external authentication server is down.
     228  </dd>
     229 
     230  <dt class="method">auth.daystocache</dt>
     231  <dd>
     232    How many days a cached password is valid if that is enabled. A value of 0
     233    caches the passwords for ever.
     234  </dd>
     235 
     236  </dl>
     237 
    194238  <a name="jobqueue"></a>
    195239  <h2>3. Internal job queue section</h2>

  • trunk/doc/development/plugins/authentication/index.html

    r2304 r2977  
    4343  <div class="abstract">
    4444 
    45     TODO
    46  
     45    <p>
     46    This document desribes how to create a plugin that uses an
     47    external solution to authenticte users.
     48    </p>
    4749    <p>
    4850    <b>Contents</b>
    4951    </p>
    5052    <ol>
    51       <li>
    52 
     53      <li><a href="#overview">Internal vs. external authentication</a></li>
     54      <li><a href="#authenticator">The Authenticator interface</a></li>
     55      <li><a href="#config">Configuration settings</a></li>
    5356    </ol>
    5457    <p>
    5558    <b>See also</b>
    5659    <ul>
    57     <li>
     60    <li><a href="../../../admin/base.config.html#authentication">base.config reference:
     61      Authentication section</a>
     62    <li><a href="../../../api/net/sf/basedb/core/authentication/package-summary.html"
     63      >Javadoc for the authentication package</a>
    5864    </ul>
    5965    </p>
    … …  
    6369    </p>
    6470  </div>
     71 
     72  <a name="overview"></a>
     73  <h2>1. Internal vs. external authentication</h2>
     74  <p>
     75    BASE can authenticate users in two ways. Either it uses the internal authentiction
     76    or the external authentication. With internal authentication BASE stores logins and
     77    passwords in it's own database. With external authentication this is handled by
     78    some external application. Even with external authentication it is possible to
     79    let BASE cache the logins/passwords. This makes it possible to login to BASE if
     80    the external authentication server is down.
     81  </p>
     82 
     83  <p>
     84    An external authentication server can only be used to grant or deny a user
     85    access to BASE. It can't be used to give a user permissions inside BASE.
     86  </p>
     87 
     88  <p>
     89    The external authentication service is only used when a user logs in.
     90    Now, one of several things can happen:
     91  </p>
     92 
     93  <ul>
     94  <li>
     95    The login is correct and the user already exists in BASE. If the driver
     96    supports extra information and <code>auth.synchronize</code> is set the
     97    extra information is copied to the BASE server.
     98  </li>
     99 
     100  <li>
     101    The login is correct, but the user doesn't exists in BASE. A new user
     102    account is created. If the driver supports extra information it is copied
     103    to the BASE server (event if the <code>auth.synchronize</code> isn't set).
     104    The new user account will get the default quota and be added to the
     105    <code>Users</code> role. In the future it may be possible that this is
     106    configurable.
     107  </li>
     108 
     109  <li>
     110    The ROOT user is logging in. Internal authentication is always used for
     111    the root user.
     112  </li>
     113 
     114  <li>
     115    If password caching is enabled, the password is copied to BASE. If an
     116    expiration timeout has been set, the user will get an expiration date
     117    set.
     118  </li>
     119 
     120  <li>
     121    The authentication server says that the login is invalid or the password
     122    is incorrect. The user will not be logged in. If a user account with the
     123    specified login already exists in BASE, it will be disabled.
     124  </li>
     125 
     126  <li>
     127    The authentication driver says that something else is wrong. If password
     128    caching is enabled, internal authentication will be used. Otherwise
     129    the user will not be logged in. An already existing account is not modified
     130    or disabled.
     131  </li>
     132  </ul>
     133
     134  <a name="overview"></a>
     135  <h2>2. The Authenticator interface</h2>
     136  <p>
     137    To be able to use external authentication you must have a class that implements
     138    the <code><a href="../../../api/net/sf/basedb/core/authentication/Authenticator.html"
     139    >Authenticator</a></code> interface. In your <code>base.config</code> file you
     140    specify the class name in the <code>auth.driver</code> setting and it's
     141    initialisation parameters in the <code>auth.init</code> setting.
     142  </p>
     143 
     144  <p>
     145    Your class must have a public no-argument constructor. The BASE application will
     146    create only one instance of the class for lifetime of the BASE server. It must be
     147    thread-safe since it may be invoked by multiple threads at the same time.
     148    Here are the methods that you must implement:
     149  </p>
     150 
     151  <dl>
     152  <dt class="method">public void init(String settings);</dt>
     153  <dd>
     154    This method is called just after the object has been created with
     155    it's argument taken from the <code>secondary.storage.driverauth.init</code>
     156    setting in your <code>base.config</code> file. This method is only
     157    called once for an object. The syntax and meaning of the parameter
     158    is driver-dependent. It is irrelevant for the BASE core. 
     159  </dd>
     160 
     161  <dt class="method">public boolean supportsExtraInformation();</dt> 
     162  <dd>
     163    This method should simply return TRUE or FALSE depending on if
     164    the authentication driver supports extra user information or not.
     165    The only required information about a user is a unique ID and the
     166    login. Extra information includes name, address, phone, email, etc.
     167  </dd>
     168
     169  <dt class="method">public AuthenticationInformation authenticate(String login,
     170    String password)</dt>
     171  <dd>
     172    Try to authenticate a login/password combination. The driver should
     173    return an <code>AuthenticationInformation</code> object if the authentication
     174    is successful or throw an exception if not. Exceptions:
     175    <ul>
     176    <li><code>UnknownLoginException</code>: This exception should be thrown
     177      if the login is not know to the external authentication system</li>
     178    <li><code>InvalidPasswordException</code>: This exception should be thrown
     179      if the login is know but the password is invalid. In case it is
     180      considered a security issue to reveal that a login exists,
     181      the plugin may throw an <code>UnknowLoginException</code> instead.</li>
     182    <li><code>AuthenticationException</code>: In case there is another problem,
     183      such as the authentication service beeing down. This exception is the only
     184      one that triggers the use of cached passwords.</li>
     185    </ul>
     186  </dd>
     187  </dl>
     188
     189  <a name="config"></a>
     190  <h2>3. Configuration settings</h2>
     191 
     192  <p>
     193    The configuration settings for the authentication driver is
     194    located in the <code>base.config</code> file. Here is an overview of
     195    the settings. For more information read the
     196    <a href="../../../admin/base.config.html#authentication">base.config reference</a>
     197  </p>
     198 
     199  <dl>
     200  <dt>auth.driver</dt>
     201  <dd>
     202    The class name of the authentication plugin.
     203  </dd>
     204
     205  <dt>auth.init</dt>
     206  <dd>
     207    Initialisation paramters sent to the plugin by calling the
     208    <code>init()</code> method.
     209  </dd>
     210 
     211  <dt>auth.synchronize</dt>
     212  <dd>
     213    If extra user information is synchronized at login time or not.
     214    This setting is ignored if the driver doesn't support extra information.
     215  </dd>
     216 
     217  <dt>auth.cachepasswords</dt>
     218  <dd>
     219    If passwords should be cached by BASE or not. If the passwords are cached a user
     220    may login to BASE even if the external authentication server is down.
     221  </dd>
     222 
     223  <dt>auth.daystocache</dt>
     224  <dd>
     225    How many days to cache the passwords if that is enabled. A value of 0
     226    caches the passwords for ever.
     227  </dd>
     228 
     229  </dl>
    65230
    66231</body>
Note: See TracChangeset for help on using the changeset viewer.