Changeset 6429


Ignore:
Timestamp:
Mar 10, 2014, 9:24:52 AM (9 years ago)
Author:
Nicklas Nordborg
Message:

References #1599: Convert authentication plug-in system to an extension point

Updated documentation.

Location:
trunk
Files:
5 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/appendix/base.config.xml

    r6080 r6429  
    270270      going to use external authentication. If you let BASE handle this
    271271      you will not have to bother about these settings. See
    272       <xref linkend="plugin_developer.other.authentication"/> for more information about
     272      <xref linkend="extensions_developer.login-manager"/> for more information about
    273273      external authentication.
    274274    </para>
    … …  
    276276    <variablelist>
    277277    <varlistentry>
    278       <term><property>auth.driver</property></term>
    279       <listitem>
    280         <para>
    281         The class name of the plug-in that acts as the authentication driver.
    282         BASE ships with a simple plug-in that checks if a user has a valid email
    283         account on a POP3 server. It is not enabled by default. The class name
    284         of that plug-in is <classname docapi="net.sf.basedb.core.authentication">net.sf.basedb.core.authentication.POP3Authenticator</classname>.
    285         If no class is specified internal authentication is used.
    286           </para>
    287       </listitem>
    288     </varlistentry>
    289    
    290     <varlistentry>
    291       <term><property>auth.jarpath</property></term>
    292       <listitem>
    293         <para>
    294         The path to the JAR file containing the class specified by the
    295         <property>auth.driver</property> setting. If empty, it is assumed that
    296         class is on the class-path. Eg. in the <filename>WEB-INF/lib</filename>
    297         directory.
    298           </para>
    299       </listitem>
    300     </varlistentry>
    301    
    302     <varlistentry>
    303       <term><property>auth.init</property></term>
    304       <listitem>
    305         <para>
    306         Initialisation parameters sent to the plug-in when calling the
    307         <methodname>init()</methodname> method. The syntax and meaning of this
    308         string depends on the plug-in. For the <classname docapi="net.sf.basedb.core.authentication">POP3Authenticator</classname>
    309         this is simply the name or IP-address of the mail server.
    310           </para>
    311       </listitem>
    312     </varlistentry>
    313    
    314     <varlistentry>
    315278      <term><property>auth.synchronize</property></term>
    316279      <listitem>
    317280        <para>
    318281        If this setting is 1 or TRUE, BASE will synchronize the extra
    319         information (name, address, email, etc.) sent by the authentication driver
    320         when a user logs in to BASE. This setting is ignored if the driver does not
    321         support extra information.
     282        information (name, address, email, etc.) sent by the authentication manager
     283        when a user logs in to BASE. This setting is ignored if the manager does not
     284        provide extra information.
    322285          </para>
    323286      </listitem>

  • trunk/doc/src/docbook/appendix/incompatible.xml

    r6410 r6429  
    9898      allowed in property names.
    9999    </para>
     100   
     101    <bridgehead>External authentication has been converted to an extension point</bridgehead>
     102    <para>
     103      External authentication plug-ins using the old system are supported through a
     104      wrapper extension, but the recommendation is to update those plug-in to the
     105      new system. See <xref linkend="extensions_developer.login-manager" /> for more information.
     106    </para>
     107   
    100108  </sect1>
    101109 

  • trunk/doc/src/docbook/developer/extensions.xml

    r6417 r6429  
    23292329    </sect2>
    23302330   
     2331    <sect2 id="extensions_developer.login-manager">
     2332      <title>Login manager</title>
     2333      <para>
     2334        This extension point makes it possible to authenticate users by some other means than
     2335        the regular internal username+password authentication. Authentication managers should
     2336        implement the <classname docapi="net.sf.basedb.core.authentication">AuthenticationManager</classname>
     2337        action interface. This interface is simple and contain only one parameter-less method
     2338        <methodname>authenticate()</methodname>. There are three outcomes:
     2339      </para>
     2340     
     2341      <itemizedlist>
     2342        <listitem>
     2343          <para>A <classname docapi="net.sf.basedb.core.authentication">AuthenticatedUser</classname>
     2344          is returned with information about a user that has passed authentication.
     2345          </para>
     2346        </listitem>
     2347       
     2348        <listitem>
     2349          <para>A <constant>null</constant> value is returned to indicate that the manager could
     2350          not determine if the login credentials are valid or not. The BASE core may try another
     2351          authentication manager or use internal authentication.
     2352          </para>
     2353        </listitem>
     2354       
     2355        <listitem>
     2356          <para>An exception is thrown to indicate that the manager has determined that
     2357          the login credentials are invalid.
     2358          </para>
     2359        </listitem>
     2360       
     2361      </itemizedlist>
     2362     
     2363      <para>
     2364        Since the action interface doesn't contain any parameters that contain information about the
     2365        login request, the implementation need to get this from the <classname
     2366        docapi="net.sf.basedb.util.extensions">ClientContext</classname> that is passed to the
     2367        action factory. The <methodname>getCurrentItem()</methodname> item is a <classname
     2368        docapi="net.sf.basedb.core.authentication">LoginRequest</classname> containing the login and
     2369        password the user entered on the login page. The <classname>ClientContext</classname>
     2370        ojbect can be cast to <classname docapi="net.sf.basedb.core">AuthenticationContext</classname>
     2371        which provide some extra services to the authentication manager.
     2372      </para>
     2373     
     2374      <sect3 id="extensions_developer.login-manager.internal-vs-external">
     2375        <title>Internal vs. external authentation</title>
     2376     
     2377        <para>
     2378          All login requests (except ROOT) are always sent to registered authentication
     2379          managers first. Internal authentication is only used if no authentication
     2380          manager could validate the user. Even with external authentication it is possible to
     2381          let BASE cache the logins/passwords. This makes it possible to login to
     2382          BASE if the external authentication server is down.
     2383        </para>
     2384       
     2385        <note>
     2386          <para>
     2387          An external authentication server can only be used to grant or deny
     2388          a user access to BASE. It cannot be used to give a user permissions,
     2389          or put a user into groups or different roles inside BASE.
     2390          </para>
     2391        </note>
     2392
     2393        <para>
     2394          The authentication process goes something like this:
     2395         
     2396          <itemizedlist>
     2397          <listitem>
     2398            <para>
     2399              The ROOT user is logging on. Internal authentication is always
     2400              used for the root user and no authentication managers are used.
     2401            </para>
     2402          </listitem>
     2403
     2404          <listitem>
     2405            <para>
     2406              An external authentication manager determines that the login request
     2407              is valid and the user is already known to BASE.
     2408              If the extra information (name, email, phone, etc.) is supplied
     2409              and the <property>auth.synchronize</property> setting
     2410              is <constant>TRUE</constant> the extra information is copied to
     2411              the BASE server.
     2412            </para>
     2413          </listitem>
     2414         
     2415          <listitem>
     2416            <para>
     2417              An external authentication manager determines that the login request
     2418              is valid, but the user is not known to BASE. This happens
     2419              the first time a user logs in. BASE will create
     2420              a new user account. If the authentication manager provides extra information, it
     2421              is copied to the BASE server (even if <property>auth.synchronize</property>
     2422              is not set). The new user account will get the default quota
     2423              and be added to the all roles and groups which has been
     2424              marked as <emphasis>default</emphasis>.
     2425            </para>
     2426          </listitem>
     2427
     2428          <listitem>
     2429            <para>
     2430              If password caching is enabled, the password is copied to BASE.
     2431              If an expiration timeout has been set, an expiration date
     2432              will be calculated and set on the user account. The expiration
     2433              date is only checked when the external authentication server is
     2434              down.
     2435            </para>
     2436          </listitem>
     2437
     2438          <listitem>
     2439            <para>
     2440              The external authentication manager says that the login is invalid or
     2441              the password is incorrect. The user will not be logged in.
     2442            </para>
     2443          </listitem>
     2444         
     2445          <listitem>
     2446            <para>
     2447              The authentication manager says that something else is wrong.
     2448              If password caching is enabled, internal authentication will be
     2449              used. Otherwise the user will not be logged in.
     2450            </para>
     2451          </listitem>
     2452          </itemizedlist>
     2453         
     2454        </para>
     2455      </sect3>
     2456     
     2457      <sect3 id="pextensions_developer.login-manager.settings">
     2458        <title>Configuration settings</title>
     2459     
     2460        <para>
     2461          The configuration settings for the authentication system are located
     2462          in the <filename>base.config</filename> file.
     2463          Here is an overview of the settings. For more information read
     2464          <xref linkend="appendix.base.config.authentication" />.
     2465        </para>
     2466       
     2467        <variablelist>
     2468        <varlistentry>
     2469          <term><property>auth.synchronize</property></term>
     2470          <listitem>
     2471            <para>
     2472            If extra user information is synchronized at login time or not.
     2473            This setting is ignored if the driver does not support extra information.
     2474            </para>
     2475          </listitem>
     2476        </varlistentry>
     2477       
     2478        <varlistentry>
     2479          <term><property>auth.cachepasswords</property></term>
     2480          <listitem>
     2481            <para>
     2482              If passwords should be cached by BASE or not. If the passwords are
     2483              cached a user may login to BASE even if the external authentication
     2484              server is down.
     2485            </para>
     2486          </listitem>
     2487        </varlistentry>
     2488       
     2489        <varlistentry>
     2490          <term><property>auth.daystocache</property></term>
     2491          <listitem>
     2492            <para>
     2493              How many days to cache the passwords if caching has been enabled.
     2494              A value of 0 caches the passwords for ever.     
     2495            </para>
     2496          </listitem>
     2497        </varlistentry>
     2498        </variablelist>
     2499      </sect3>
     2500     
     2501    </sect2>
     2502   
     2503    <sect2 id="extensions_developer.login-form">
     2504      <title>Login form</title>
     2505     
     2506      <para>
     2507        This extension point is typically used in combination with a login manager to provide a
     2508        customized login form. Extensions should implement the <interfacename
     2509        docapi="net.sf.basedb.clients.web.extensions.login">LoginFormAction</interfacename>
     2510        action which is used to specify prompts, tooltips, help texts and styling information
     2511        for the login and password fields. The extension point supports custom scripts and stylesheets.
     2512      </para>
     2513     
     2514      <note>
     2515        <title>Only the first registered extension is used</title>
     2516        <para>
     2517          Since there is only one login form, only the first registered extension is used even
     2518          if there are more extensions for this extension point.
     2519        </para>
     2520      </note>
     2521     
     2522    </sect2>
    23312523  </sect1>
    23322524 

  • trunk/doc/src/docbook/developer/plugins.xml

    r6129 r6429  
    34683468      <title>Authentication plug-ins</title>
    34693469     
    3470       <important>
    3471         <title>This may be converted to an extension point in the future</title>
    3472         <para>
    3473         There are certain plans to convert the authentication mechanism to
    3474         an extension point in the future. There are several benefits with this:
    3475         </para>
    3476         <itemizedlist>
    3477           <listitem>
    3478             <para>
    3479             Easier installation since code doesn't have to be installed in the
    3480             WEB-INF/lib or WEB-INF/classes directory.
    3481             </para>
    3482           </listitem>
    3483           <listitem>
    3484             <para>
    3485             Allow support for multiple authentication modules. Users could either
    3486             select a specific module, or each module could be tried in turn or
    3487             some kind of auto-discovery can maybe be implemented.
    3488             </para>
    3489           </listitem>
    3490         </itemizedlist>
    3491        
    3492         <para>
    3493           See <ulink url="http://base.thep.lu.se/ticket/1599">ticket #1599: Convert
    3494           authentication plug-in system to an extension point</ulink> for more
    3495           information.
    3496         </para>
    3497        
    3498       </important>
    3499      
    35003470      <para>
    3501         BASE provides a plug-in mechanism for authenticating users
    3502         (validating the username and password) when they are logging in.
    3503         This plug-in mechanism is not the same as the regular plug-in API.
    3504         That is, you do not have worry about user interaction or implementing the
    3505         <interfacename docapi="net.sf.basedb.core.plugin">Plugin</interfacename> interface.
     3471        This style of plug-ins have been deprecated in BASE 3.3 and replaced by
     3472        an extension point. See <xref linkend="extensions_developer.login-manager" />
     3473        for more information. Backwards compatibility is supported via a wrapper
     3474        class that is automatically enabled if the <property>auth.driver</property>
     3475        property is set.
    35063476      </para>
    3507      
    3508       <sect3 id="plugin_developer.other.authentication.internal_external">
    3509         <title>Internal vs. external authentation</title>
    3510      
    3511         <para>
    3512           BASE can authenticate users in two ways. Either it uses the internal
    3513           authentication or the external authentication. With internal
    3514           authentication BASE stores logins and passwords in its own database.
    3515           With external authentication this is handled by some external
    3516           application. Even with external authentication it is possible to
    3517           let BASE cache the logins/passwords. This makes it possible to login to
    3518           BASE if the external authentication server is down.
    3519         </para>
    3520        
    3521         <note>
    3522           <para>
    3523           An external authentication server can only be used to grant or deny
    3524           a user access to BASE. It cannot be used to give a user permissions,
    3525           or put a user into groups or different roles inside BASE.
    3526           </para>
    3527         </note>
    3528 
    3529         <para>
    3530           The external authentication service is only used when a user logs in.
    3531           Now, one or more of several things can happen:
    3532          
    3533           <itemizedlist>
    3534           <listitem>
    3535             <para>
    3536               The ROOT user is logging on. Internal authentication is always
    3537               used for the root user and the authenticator plug-in is never
    3538               used.
    3539             </para>
    3540           </listitem>
    3541 
    3542           <listitem>
    3543             <para>
    3544               The login is correct and the user is already known to BASE.
    3545               If the plug-in supports extra information (name, email, phone, etc.)
    3546               and the <property>auth.synchronize</property> setting
    3547               is <constant>TRUE</constant> the extra information is copied to
    3548               the BASE server.
    3549             </para>
    3550           </listitem>
    3551          
    3552           <listitem>
    3553             <para>
    3554               The login is correct, but the user is not known to BASE. This happens
    3555               the first time a user logs in. BASE will create
    3556               a new user account. If the driver supports extra information, it
    3557               is copied to the BASE server (even if <property>auth.synchronize</property>
    3558               is not set). The new user account will get the default quota
    3559               and be added to the all roles and groups which has been
    3560               marked as <emphasis>default</emphasis>.
    3561             </para>
    3562           </listitem>
    3563 
    3564           <listitem>
    3565             <para>
    3566               If password caching is enabled, the password is copied to BASE.
    3567               If an expiration timeout has been set, an expiration date
    3568               will be calculated and set on the user account. The expiration
    3569               date is only checked when the external authentication server is
    3570               down.
    3571             </para>
    3572           </listitem>
    3573 
    3574           <listitem>
    3575             <para>
    3576               The authentication server says that the login is invalid or
    3577               the password is incorrect. The user will not be logged in.
    3578               If a user account with the specified login already exists in
    3579               BASE, it will be disabled.
    3580             </para>
    3581           </listitem>
    3582          
    3583           <listitem>
    3584             <para>
    3585               The authentication driver says that something else is wrong.
    3586               If password caching is enabled, internal authentication will be
    3587               used. Otherwise the user will not be logged in. An already
    3588               existing account is not modified or disabled.
    3589             </para>
    3590           </listitem>
    3591           </itemizedlist>
    3592          
    3593         </para>
    3594       </sect3>
    3595      
    3596       <sect3 id="plugin_developer.other.authentication.authenticator">
    3597         <title>The Authenticator interface</title>
    3598        
    3599         <para>
    3600           To be able to use external authentication you must create a class
    3601           that implements the
    3602           <interfacename docapi="net.sf.basedb.core.authentication">net.sf.based.core.authentication.Authenticator</interfacename>
    3603           interface. Specify the name of the class in the <property>auth.driver</property>
    3604           setting in <filename>base.config</filename> and
    3605           its initialisation parameters in the <property>auth.init</property> setting.
    3606           The class can either be installed on Tomcat's class path (eg. <filename>WEB-INF/lib</filename>)
    3607           or on an external path. In the latter case the <property>auth.jarpath</property>
    3608           must be set in <filename>base.config</filename>.
    3609         </para>
    3610        
    3611         <para>
    3612           Your class must have a public no-argument constructor. The BASE
    3613           application will create only one instance of the class for lifetime
    3614           of the BASE server. It must be thread-safe since it may be invoked by
    3615           multiple threads at the same time. Here are the methods that you must
    3616           implement
    3617         </para>
    3618        
    3619         <variablelist>
    3620         <varlistentry>
    3621           <term>
    3622             <methodsynopsis language="java">
    3623               <modifier>public</modifier>
    3624               <void/>
    3625               <methodname>init</methodname>
    3626               <methodparam>
    3627                 <type>String</type>
    3628                 <parameter>settings</parameter>
    3629               </methodparam>
    3630               <exceptionname>AuthenticationException</exceptionname>
    3631             </methodsynopsis>
    3632           </term>
    3633           <listitem>
    3634             <para>
    3635             This method is called just after the object has been created with its argument
    3636             taken from the <property>auth.init</property> setting in your <filename>base.config</filename>
    3637             file. This method is only called once for an instance of the object. The syntax and meaning of
    3638             the parameter is driver-dependent and should be documented by the plug-in.
    3639             It is irrelevant for the BASE core.
    3640             </para>
    3641           </listitem>
    3642         </varlistentry>
    3643        
    3644         <varlistentry>
    3645           <term>
    3646             <methodsynopsis language="java">
    3647               <modifier>public</modifier>
    3648               <type>boolean</type>
    3649               <methodname>supportsExtraInformation</methodname>
    3650             </methodsynopsis>
    3651           </term>
    3652           <listitem>
    3653             <para>
    3654             This method should simply return <constant>TRUE</constant> or <constant>FALSE</constant>
    3655             depending on if the plug-in supports extra user information or not. The only required
    3656             information about a user is a unique ID and the login. Extra information includes
    3657             name, address, phone, email, etc.
    3658             </para>
    3659           </listitem>       
    3660         </varlistentry>
    3661 
    3662         <varlistentry>
    3663           <term>
    3664             <methodsynopsis language="java">
    3665               <modifier>public</modifier>
    3666               <type>AuthenticationInformation</type>
    3667               <methodname>authenticate</methodname>
    3668               <methodparam>
    3669                 <type>String</type>
    3670                 <parameter>login</parameter>
    3671               </methodparam>
    3672               <methodparam>
    3673                 <type>String</type>
    3674                 <parameter>password</parameter>
    3675               </methodparam>
    3676               <exceptionname>UnknownLoginException</exceptionname>
    3677               <exceptionname>InvalidPasswordException</exceptionname>
    3678               <exceptionname>LoginException</exceptionname>
    3679               <exceptionname>AuthenticationException</exceptionname>
    3680             </methodsynopsis>
    3681           </term>
    3682           <listitem>
    3683             <para>
    3684             Try to authenticate a login/password combination. The plug-in should return
    3685             an <classname docapi="net.sf.basedb.core.authentication">AuthenticationInformation</classname> object if the
    3686             authentication is successful or throw an exception if not.
    3687            
    3688             There are three exceptions to choose from:
    3689            
    3690             <itemizedlist>
    3691             <listitem>
    3692               <para>
    3693               <exceptionname>UnknownLoginException</exceptionname>:
    3694               This exception should be thrown if the login is not known to the
    3695               external authentication system.
    3696               </para>
    3697             </listitem>
    3698 
    3699             <listitem>
    3700               <para>
    3701               <exceptionname>InvalidPasswordException</exceptionname>:
    3702               This exception should be thrown if the login is known but the
    3703               password is invalid. In case it is considered a security issue
    3704               to reveal that a login exists, the plugin may throw an
    3705               <exceptionname>UnknowLoginException</exceptionname> or
    3706               <exceptionname>LoginException</exceptionname> instead.
    3707               </para>
    3708             </listitem>
    3709 
    3710             <listitem>
    3711               <para>
    3712               <exceptionname>LoginException</exceptionname>:
    3713               This exception should be thrown if the login failed but it
    3714               is not known if the cause is an incorrect login or password.
    3715               The authenticator implementation must specify an error message
    3716               that is displayed to the user.
    3717               </para>
    3718             </listitem>
    3719            
    3720             <listitem>
    3721               <para>
    3722               <exceptionname>AuthenticationException</exceptionname>:
    3723               In case there is another problem, such as the authentication service
    3724               being down. This exception triggers the use of cached passwords
    3725               if caching has been enabled.
    3726               </para>
    3727             </listitem>
    3728             </itemizedlist>
    3729             </para>
    3730           </listitem>       
    3731         </varlistentry>
    3732         </variablelist>
    3733       </sect3>
    3734      
    3735       <sect3 id="plugin_developer.other.authentication.settings">
    3736         <title>Configuration settings</title>
    3737      
    3738         <para>
    3739           The configuration settings for the authentication driver are located
    3740           in the <filename>base.config</filename> file.
    3741           Here is an overview of the settings. For more information read
    3742           <xref linkend="appendix.base.config.authentication" />.
    3743         </para>
    3744        
    3745         <variablelist>
    3746         <varlistentry>
    3747           <term><property>auth.driver</property></term>
    3748           <listitem>
    3749             <para>
    3750             The class name of the authentication plug-in.
    3751             </para>
    3752           </listitem>
    3753         </varlistentry>
    3754 
    3755         <varlistentry>
    3756           <term><property>auth.jarpath</property></term>
    3757           <listitem>
    3758             <para>
    3759             The path to the JAR file containing the authentication plug-in.
    3760             This should be left empty if the plug-in is installed in the
    3761             <filename>WEB-INF/lib</filename> directory.
    3762             </para>
    3763           </listitem>
    3764         </varlistentry>
    3765 
    3766         <varlistentry>
    3767           <term><property>auth.init</property></term>
    3768           <listitem>
    3769             <para>
    3770             Initialisation parameters sent to the plug-in when calling the
    3771             <methodname>Authenticator.init()</methodname> method.
    3772             </para>
    3773           </listitem>
    3774         </varlistentry>
    3775        
    3776         <varlistentry>
    3777           <term><property>auth.synchronize</property></term>
    3778           <listitem>
    3779             <para>
    3780             If extra user information is synchronized at login time or not.
    3781             This setting is ignored if the driver does not support extra information.
    3782             </para>
    3783           </listitem>
    3784         </varlistentry>
    3785        
    3786         <varlistentry>
    3787           <term><property>auth.cachepasswords</property></term>
    3788           <listitem>
    3789             <para>
    3790               If passwords should be cached by BASE or not. If the passwords are
    3791               cached a user may login to BASE even if the external authentication
    3792               server is down.
    3793             </para>
    3794           </listitem>
    3795         </varlistentry>
    3796        
    3797         <varlistentry>
    3798           <term><property>auth.daystocache</property></term>
    3799           <listitem>
    3800             <para>
    3801               How many days to cache the passwords if caching has been enabled.
    3802               A value of 0 caches the passwords for ever.     
    3803             </para>
    3804           </listitem>
    3805         </varlistentry>
    3806         </variablelist>
    3807       </sect3>
    38083477     
    38093478    </sect2>

  • trunk/src/core/net/sf/basedb/core/AuthenticationContext.java

    r6427 r6429  
    4646  AuthenticationContext(SessionControl sc, org.hibernate.Session session, LoginRequest loginRequest)
    4747  {
    48     super(sc, null, null);
     48    super(sc, null, loginRequest);
    4949    this.session = session;
    5050    this.loginRequest = loginRequest;
Note: See TracChangeset for help on using the changeset viewer.