Dec 6, 2018, 2:33:35 PM (4 years ago)
Nicklas Nordborg

References #2131: Add support for installing multiple authentication managers

Updated developer documentation about supporting multiple login managers on a single server.

1 edited


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

    r7274 r7543  
    24982498        the regular internal username+password authentication. Authentication managers should
    24992499        implement the <classname docapi="net.sf.basedb.core.authentication">AuthenticationManager</classname>
    2500         action interface. This interface is simple and contain only one parameter-less method
    2501         <methodname>authenticate()</methodname>. There are three outcomes:
     2500        action interface. This interface is simple and the only method that is required to implement
     2501        is the parameter-less <methodname>authenticate()</methodname> method. There are three outcomes:
    25022502      </para>
    25342534        which provide some extra services to the authentication manager.
    25352535      </para>
     2537      <sect3 id="extensions_developer.login-manager.multiple">
     2538        <title>Supporting multiple installed login managers</title>
     2540        <para>
     2541          As of BASE 3.14 it should be easier to support server configurations that
     2542          include multiple login manages. The <code>login-form</code> attribute in the
     2543          <classname>LoginRequest</classname> parameter contains the login form
     2544          that was used by the user. A login manager should check this value
     2545          to decide if the login request should be handled or not. Note that
     2546          the value may be missing.
     2547        </para>
     2549        <para>
     2550          The <classname docapi="net.sf.basedb.core.authentication">AuthenticationManager</classname>
     2551          interface also includes an optional method,
     2552          <methodname>vetoAuthenticatedUser(UserData, AuthenticatedUser)</methodname>. This method
     2553          is only called if one of the installed login manager authenticated the user successfully.
     2554          Then, all other installed login managers get a chance to raise a veto by throwing an
     2555          exception from this method. A responsible login manager probably need to implement this
     2556          method to detect if a user that is supposed to login with a specific method is trying to
     2557          login with some other method. Examples of actual implementations can be found in the
     2558          the <ulink
     2559          url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.yubikey">YubiKey</ulink>
     2560          and <ulink
     2561          url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.otp">OTP</ulink> extensions.
     2562        </para>
     2564      </sect3>
    25372566      <sect3 id="extensions_developer.login-manager.internal-vs-external">
    26702699      <note>
    2671         <title>Only the first registered extension is used</title>
     2700        <title>As of BASE 3.14 it is possible to install multiple login managers</title>
    26722701        <para>
    2673           Since there is only one login form, only the first registered extension is used even
    2674           if there are more extensions for this extension point.
     2702          All installed and enabled login forms are available in a selection list
     2703          from which the user can select to switch to another login form. For technical reasons
     2704          custom scripts and stylesheets are loaded for all installed login forms even
     2705          though only one is displayed at a time. Developers must ensure that CSS rules
     2706          and scripts are not affecting other login forms than the intended one.
    26752707        </para>
     2708        <para>
     2709          To help with this, BASE is setting two data-attributes on the
     2710          <sgmltag class="starttag">body</sgmltag> tag:
     2711        </para>
     2713        <variablelist>
     2714        <varlistentry>
     2715          <term><property>data-login-form</property></term>
     2716          <listitem>
     2717            <para>
     2718            The ID of the currently active login form.
     2719            </para>
     2720          </listitem>
     2721        </varlistentry>
     2722        <varlistentry>
     2723          <term><property>data-requested-form</property></term>
     2724          <listitem>
     2725            <para>
     2726            The ID of the login form that was requested. This may differ from the currently active
     2727            if it is not installed or enabled.
     2728            </para>
     2729          </listitem>
     2730        </varlistentry>
     2731        </variablelist>
     2733        <para>
     2734          In CSS files, rules that are targeting elements on the login form should match
     2735          against the <sgmltag class="attribute">data-login-form</sgmltag> attribute in the selector,
     2736          for example:
     2737        </para>
     2739        <programlisting language="css">
     2740/* Example from the YubiKey login form */
     2742   #loginform #login-row th
     2744   background-image: url('../images/yubico.png');
     2745   background-position: right center;
     2746   background-repeat: no-repeat;
     2747   padding-right: 20px;
     2751        <para>
     2752          Scripts should also check the value of this attribute before doing stuff:
     2753        </para>
     2754        <programlisting language="javascript">
     2755/* Examle from the OTP login form */
     2756if (Data.get(document.body, 'login-form') != 'net.sf.basedb.otp.login-form')
     2758   // Not the OTP login form
     2759   return;
     2763        <para>
     2764          When logging in, the ID of the selected login form is added to the
     2765          <classname docapi="net.sf.basedb.core.authentication">LoginRequest</classname>
     2766          with attribute name <code>login-form</code> so that login managers can
     2767          pick it up and take action on it.
     2768        </para>
    26762770      </note>
Note: See TracChangeset for help on using the changeset viewer.