Changeset 7543 for trunk/doc/src/docbook/developer/extensions.xml

Timestamp:

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

Author:

Nicklas Nordborg

Message:

References #2131: Add support for installing multiple authentication managers

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

File:

• trunk/doc/src/docbook/developer/extensions.xml (modified) (3 diffs)

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

@@ -2498 +2498 @@
         the regular internal username+password authentication. Authentication managers should
         implement the <classname docapi="net.sf.basedb.core.authentication">AuthenticationManager</classname>
-        action interface. This interface is simple and contain only one parameter-less method
-        <methodname>authenticate()</methodname>. There are three outcomes:
+        action interface. This interface is simple and the only method that is required to implement
+        is the parameter-less <methodname>authenticate()</methodname> method. There are three outcomes:
       </para>
       
@@ -2534 +2534 @@
         which provide some extra services to the authentication manager.
       </para>
+      
+      <sect3 id="extensions_developer.login-manager.multiple">
+        <title>Supporting multiple installed login managers</title>
+        
+        <para>
+          As of BASE 3.14 it should be easier to support server configurations that
+          include multiple login manages. The <code>login-form</code> attribute in the
+          <classname>LoginRequest</classname> parameter contains the login form
+          that was used by the user. A login manager should check this value 
+          to decide if the login request should be handled or not. Note that 
+          the value may be missing.
+        </para>
+        
+        <para>
+          The <classname docapi="net.sf.basedb.core.authentication">AuthenticationManager</classname>
+          interface also includes an optional method, 
+          <methodname>vetoAuthenticatedUser(UserData, AuthenticatedUser)</methodname>. This method
+          is only called if one of the installed login manager authenticated the user successfully. 
+          Then, all other installed login managers get a chance to raise a veto by throwing an
+          exception from this method. A responsible login manager probably need to implement this
+          method to detect if a user that is supposed to login with a specific method is trying to
+          login with some other method. Examples of actual implementations can be found in the
+          the <ulink 
+          url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.yubikey">YubiKey</ulink>
+          and <ulink 
+          url="http://baseplugins.thep.lu.se/wiki/net.sf.basedb.otp">OTP</ulink> extensions.
+        </para>
+        
+      </sect3>
       
       <sect3 id="extensions_developer.login-manager.internal-vs-external">
@@ -2669 +2698 @@
       
       <note>
-        <title>Only the first registered extension is used</title>
+        <title>As of BASE 3.14 it is possible to install multiple login managers</title>
         <para>
-          Since there is only one login form, only the first registered extension is used even
-          if there are more extensions for this extension point.
+          All installed and enabled login forms are available in a selection list
+          from which the user can select to switch to another login form. For technical reasons 
+          custom scripts and stylesheets are loaded for all installed login forms even
+          though only one is displayed at a time. Developers must ensure that CSS rules
+          and scripts are not affecting other login forms than the intended one.
         </para>
+        <para>
+          To help with this, BASE is setting two data-attributes on the 
+          <sgmltag class="starttag">body</sgmltag> tag:
+        </para>
+        
+        <variablelist>
+        <varlistentry>
+          <term><property>data-login-form</property></term>
+          <listitem>
+            <para>
+            The ID of the currently active login form.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><property>data-requested-form</property></term>
+          <listitem>
+            <para>
+            The ID of the login form that was requested. This may differ from the currently active
+            if it is not installed or enabled.
+            </para>
+          </listitem>
+        </varlistentry>
+        </variablelist>
+        
+        <para>
+          In CSS files, rules that are targeting elements on the login form should match
+          against the <sgmltag class="attribute">data-login-form</sgmltag> attribute in the selector,
+          for example:
+        </para>
+        
+        <programlisting language="css">
+/* Example from the YubiKey login form */
+body[data-login-form="net.sf.basedb.yubikey.login-form"] 
+   #loginform #login-row th
+{
+   background-image: url('../images/yubico.png');
+   background-position: right center;
+   background-repeat: no-repeat;
+   padding-right: 20px;
+}
+</programlisting>
+        
+        <para>
+          Scripts should also check the value of this attribute before doing stuff:
+        </para>
+        <programlisting language="javascript">
+/* Examle from the OTP login form */
+if (Data.get(document.body, 'login-form') != 'net.sf.basedb.otp.login-form') 
+{
+   // Not the OTP login form
+   return;
+}
+</programlisting>
+
+        <para>
+          When logging in, the ID of the selected login form is added to the
+          <classname docapi="net.sf.basedb.core.authentication">LoginRequest</classname>
+          with attribute name <code>login-form</code> so that login managers can
+          pick it up and take action on it.
+        </para>
+
       </note>