<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//UR1//DTD docbookAllegeEsup//FR"
"http://www.esup-portail.org/consortium/espace/docbook/xxe/dtd/docbook_allege_esup.dtd">
<article lang="FR">
  <title>The ESUP authentication layer</title>

  <articleinfo>
    <abstract>
      <para>This document deals with the ESUP authentication layer.</para>
    </abstract>

    <author>
      <firstname>Thomas Bellembois</firstname>

      <surname></surname>

      <affiliation>
        <orgname><ulink url="http://">University of Rennes 1</ulink></orgname>
      </affiliation>
    </author>

    <revhistory>
      <revision>
        <revnumber>1.0</revnumber>

        <date>Thomas Bellembois (University of Rennes1)</date>

        <revdescription>
          <para>first release</para>
        </revdescription>
      </revision>
    </revhistory>
  </articleinfo>

  <section>
    <title>Introduction</title>

    <para>The ESUP authentication layer is a versatile authentication layer,
    to be accessed by many different clients (web browsers, operating systems,
    applications…) :<itemizedlist>
        <listitem>
          <para>Web browsers that may support only HTTP scheme (not WebDAV
          extensions) but redirections and HTTP basic authentication scheme
          (realms);</para>
        </listitem>

        <listitem>
          <para>Operating systems and system applications that may be fully
          WebDAV-compliant but do not implement redirections and/or form
          completion (and thus can not respond to SSO requests);</para>
        </listitem>

        <listitem>
          <para>Web applications that may be SSO-compliant but not
          always.</para>
        </listitem>
      </itemizedlist></para>

    <para>This versatility is achieved with a highly configurable
    authentication layer shown in figure&#160;3, made up of an authentication
    router that chooses between three authentication filters:<itemizedlist>
        <listitem>
          <para>CAS&#160;authentication for web browsers and
          applications,</para>
        </listitem>

        <listitem>
          <para>LDAP authentication for operating systems,</para>
        </listitem>

        <listitem>
          <para>Trusted authentication for trusted applications (based on a
          secret shared between the application and the server).</para>
        </listitem>
      </itemizedlist></para>

    <para>The selection of a filter is performed by the router, depending on
    the agent (i.e. the type of the client: browser, application…), its
    localization (IP address), the target (virtual) server name and the
    configuration set by the administrators of the server.</para>

    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="media/filters.png"></imagedata>
      </imageobject>
    </mediaobject>
  </section>

  <section>
    <title>Configuration</title>

    <section>
      <title>The router</title>

      <para>This is probably the hardest think to configure. The configuration
      is defined in the <filename>web.xml</filename> file of the
      application.</para>

      <para>Let's have a look at the configuration :</para>

      <para><programlisting>&lt;filter&gt;</programlisting></para>

      <section>
        <title>General configuration</title>

        <para>Filter name and class - you DO NOT have to modify these values
        <programlisting>&lt;filter-name&gt;authenticationRouter&lt;/filter-name&gt;
  &lt;filter-class&gt;org.esupportail.filter.authenticationRouter.AuthenticationRouter&lt;/filter-class&gt;</programlisting></para>

        <para>Here is the <emphasis role="bold">filter list</emphasis> which
        determines the filter order. In the example below the router will
        first try to match the <literal>LDAP</literal> filter criteria
        (defined after in the file) then the <literal>CAS</literal> filter...
        up to the <literal>UNAUTHENTICATED</literal> filter. <programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.filterList&lt;/param-name&gt;
   &lt;param-value&gt;LDAP CAS TRUSTED UNAUTHENTICATED&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

        <para>Now you have to configure the <emphasis role="bold">default
        authentication filter</emphasis> that is the filter used by default if
        no filter are finally selected by the router (in other words if - for
        each filter - at least one criterion DOES NOT matches the request).
        <programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.defaultAuthenticationFilter&lt;/param-name&gt;
   &lt;param-value&gt;TRUSTED&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting>The following parameter is important and
        will often be let to <userinput>false</userinput>. If
        <userinput>false</userinput>, then ONLY ONE filter will be used - the
        first one matching the request in the <emphasis role="bold">filter
        list</emphasis>. If <userinput>true</userinput> then every filter
        matching the request will be used.</para>

        <para>Imagine for example that the LDAP and TRUSTED criteria match the
        request, then the request will be first forwarded to the LDAP filter
        (for an LDAP authentication) and then to the TRUSTED filter (for a
        TRUSTED authentication) - and in this order !</para>

        <para><programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.enableCascading&lt;/param-name&gt;
   &lt;param-value&gt;false&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>
      </section>

      <section>
        <title>Selection criteria for each authentication filter</title>

        <para>The following sections define selection criteria for each
        filter. There are 4 sections of 5 criteria whose names finish by an
        authentication filter name (LDAP - CAS - TRUSTED - UNAUTHENTICATED).
        <programlisting>      &lt;!-- LDAP --&gt;
  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.allowClientIPLDAP&lt;/param-name&gt;
   &lt;param-value&gt;&lt;/param-value&gt;
  &lt;/init-param&gt;
  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.useSecureRequestLDAP&lt;/param-name&gt;
   &lt;param-value&gt;&lt;/param-value&gt;
  &lt;/init-param&gt;
  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.agentLDAP&lt;/param-name&gt;
   &lt;param-value&gt;&lt;/param-value&gt;
  &lt;/init-param&gt;
  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.httpRequestParameterLDAP&lt;/param-name&gt;
   &lt;param-value&gt;&lt;/param-value&gt;
  &lt;/init-param&gt;
  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.destinationHostLDAP&lt;/param-name&gt;
   &lt;param-value&gt;&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

        <para><important>
            <para>A filter is selected by the router if each criterion matches
            the request.</para>
          </important></para>

        <para>Let's have a look on each criterion in more details.</para>

        <para><varname>allowClientIP[FilterName]</varname> : if empty then
        there is no restriction else only requests with one of the given
        client IP adresses will be forwarded to the filter
        [FilterName].</para>

        <para><programlisting>       &lt;!-- TRUSTED --&gt;
 &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.allowClientIPTRUSTED&lt;/param-name&gt;
   &lt;param-value&gt;129.20.129.12 129.20.129.13&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

        <para><varname>useSecureRequest[FilterName]</varname> : if
        <userinput>true</userinput> then only HTTPS requests will be forwarded
        to the filter [FilterName]. <programlisting>&lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.useSecureRequestTRUSTED&lt;/param-name&gt;
   &lt;param-value&gt;false&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

        <para><varname>agent[FilterName]</varname> : if empty then there is no
        restriction else only request with one of the given client agents will
        be forwarded to the filter [FilterName]. The agent identifies the type
        of the client - mozilla, DAVFS... - <emphasis role="bold">Regular
        expressions are accepted</emphasis>.<programlisting>&lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.agentTRUSTED&lt;/param-name&gt;
   &lt;param-value&gt;*mozilla*&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

        <para><varname>httpRequestParameter[FilterName]</varname> : if empty
        then there is no restriction else only request with the given
        parameters will be forwarded to the given filter (here TRUSTED).
        <emphasis role="bold">Regular expressions are
        accepted</emphasis>.</para>

        <para><programlisting> &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.httpRequestParameterTRUSTED&lt;/param-name&gt;
   &lt;param-value&gt;auth=trusted authentication=trusted mode*=*secure*&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

        <para><varname>destinationHost[FilterName]</varname> : if empty then
        there is no restriction else only request with the given destination
        hosts will be forwarded to the given filter (here TRUSTED). <emphasis
        role="bold">Regular expressions are
        accepted</emphasis>.<programlisting> &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.authenticationRouter.destinationHostTRUSTED&lt;/param-name&gt;
   &lt;param-value&gt;webdav-restricted.univ-rennes1.fr webdav-restricted2.univ-rennes1.fr *.univ-valenciennes.fr&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>
      </section>
    </section>

    <section>
      <title>The LDAP authentication filter</title>

      <para>Processes an LDAP authentication.</para>

      <para><programlisting>&lt;filter&gt;</programlisting></para>

      <para>Filter name and class - you DO NOT have to modify these values
      <programlisting>  &lt;filter-name&gt;LDAP&lt;/filter-name&gt;
  &lt;filter-class&gt;org.esupportail.filter.LDAPFilter.LDAPFilter&lt;/filter-class&gt;</programlisting></para>

      <para>Let the following parameter to
      <userinput>true</userinput>.<programlisting>&lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.useAuthenticationRouter&lt;/param-name&gt;
   &lt;param-value&gt;true&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

      <para>LDAP directory URL's (the alternate URL is optionnal - usefull if
      the first directory does not work) <programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.connectionURL&lt;/param-name&gt;
   &lt;param-value&gt;ldap://myLdap.univ.fr:389&lt;/param-value&gt;
  &lt;/init-param&gt;
  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.alternateURL&lt;/param-name&gt;
   &lt;param-value&gt;ldap://myLdap2.univ.fr:389&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

      <para>Bind type = searchbind or fastbind</para>

      <para><itemizedlist>
          <listitem>
            <para>searchbind : The filter will first try to find the connected
            user, using the given <emphasis role="bold">base DN</emphasis>,
            <emphasis role="bold">scope</emphasis> and <emphasis
            role="bold">filter</emphasis> - and then will execute a bind
            request. </para>
          </listitem>

          <listitem>
            <para>fastbind : The filter will try to bind with the given
            <emphasis role="bold">pattern</emphasis></para>
          </listitem>
        </itemizedlist><programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.bindType&lt;/param-name&gt;
   &lt;param-value&gt;SEARCHBIND&lt;/param-value&gt; &lt;!-- FASTBIND --&gt;
  &lt;/init-param&gt;</programlisting></para>

      <para><varname>fastBindUserPattern</varname> : Pattern used to build a
      DN to bind. The syntax is
      <varname>uniqueAttributeEqualsToLogin={0},baseDN</varname>
      <programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.fastBindUserPattern&lt;/param-name&gt;
   &lt;param-value&gt;uid={0},ou=people,dc=univ,dc=fr&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

      <para>The following attributes are optionnals and specify the credential
      to connect to the LDAP if needed. <programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.searchBindConnectionName&lt;/param-name&gt;
   &lt;param-value&gt;LDAPMaster&lt;/param-value&gt;
  &lt;/init-param&gt;
  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.searchBindConnectionPassword&lt;/param-name&gt;
   &lt;param-value&gt;whatACoolWebDAVServer!&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

      <para>The tree last atributes are classical LDAP configuration
      parameters - you won't have any difficulties to understand them. ;-)
      <programlisting>&lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.searchBindBaseDN&lt;/param-name&gt;
   &lt;param-value&gt;ou=people,dc=univ,dc=fr&lt;/param-value&gt;
  &lt;/init-param&gt;
  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.searchBindScope&lt;/param-name&gt;
   &lt;param-value&gt;SUBTREE_SCOPE&lt;/param-value&gt; &lt;!-- SUBTREE_SCOPE | ONELEVEL_SCOPE | OBJECT_SCOPE --&gt;
  &lt;/init-param&gt;
  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.LDAPFilter.searchBindFilter&lt;/param-name&gt;
   &lt;param-value&gt;uid={0}&lt;/param-value&gt;
  &lt;/init-param&gt;
&lt;/filter&gt;</programlisting></para>

      <para></para>
    </section>

    <section>
      <title>The TRUSTED authentication filter</title>

      <para>Processes a TRUSTED authentication. The easiest filter to
      configure.</para>

      <para><programlisting> &lt;filter&gt;</programlisting></para>

      <para>Filter name and class - you DO NOT have to modify these values
      <programlisting>&lt;filter-name&gt;TRUSTED&lt;/filter-name&gt;
  &lt;filter-class&gt;org.esupportail.filter.trustedFilter.TrustedFilter&lt;/filter-class&gt;</programlisting></para>

      <para>Let the following parameter to <userinput>true</userinput>.
      <programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.trustedFilter.useAuthenticationRouter&lt;/param-name&gt;
   &lt;param-value&gt;true&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting>Trusted password <programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.trustedFilter.trustedPassword&lt;/param-name&gt;
   &lt;param-value&gt;[slide.trustedFilter.password]&lt;/param-value&gt;
  &lt;/init-param&gt;</programlisting></para>

      <para><emphasis role="bold">Optionnal</emphasis> allowed user list - Let
      it empty for no user restriction.<programlisting>  &lt;init-param&gt;
   &lt;param-name&gt;org.esupportail.filter.trustedFilter.trustedUsers&lt;/param-name&gt;
   &lt;param-value&gt;tbellemb:bourges:masterYoda&lt;/param-value&gt;
  &lt;/init-param&gt;
 &lt;/filter&gt;</programlisting></para>

      <para></para>
    </section>

    <section>
      <title>The UNAUTHENTICATED authentication filter</title>

      <para>There is no entry for this filter in the
      <filename>web.xml</filename> file because this filter... does not exist
      !</para>

      <para>If the authentication router selects this filter then the request
      will be directed to a non existing filter - the consequence is that the
      user name will not be included in the request going to the
      server.</para>
    </section>
  </section>
</article>