Historique de la page

{panel:bgColor=#F8F7EF}
h1. The ESUP authentication layer
{panel}
{toc:style=disc\|indent=20px\|minLevel=1}

h1. Introduction

\\

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

* 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);
* Web applications that may be SSO-compliant but not           always.

This versatility is achieved with a highly configurable     authentication layer shown in figure 3, made up of an authentication     router that chooses between three authentication filters:
* CAS authentication for web browsers and           applications,

* LDAP authentication for operating systems,
* Trusted authentication for trusted applications (based on a           secret shared between the application and the server).

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.

\!filters.png\!h1.

h1. Configuration

\\

h2. The router

This is probably the hardest think to configure. The configuration       is defined in the *web.xml* file of the application.       The different parameters values of the *web.xml* are       defined in the *build.properties*.

Let's have a look at the configuration of the       web.xml:
{code}
<filter>
{code}

h3. General configuration

\\

Filter name and class - you DO NOT have to modify these values\\

{code}
<filter-name>authenticationRouter</filter-name>
  <filter-class>org.esupportail.filter.authenticationRouter.AuthenticationRouter</filter-class>
{code}\\ 
Here is the *slide.authenticationRouter.filterList* which         determines the filter order. In the example below the router will         first try to match the LDAP filter criteria         (defined after in the file) then the CAS filter...         up to the UNAUTHENTICATED filter.
\\ \\
{code}
<init-param>
   <param-name>org.esupportail.filter.authenticationRouter.filterList</param-name>
   <param-value>LDAP CAS TRUSTED UNAUTHENTICATED</param-value>
  </init-param>
{code}\\ 
Now you have to configure the *slide.authenticationRouter.defaultAuthenticationFilter* 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).
\\ \\
{code}
<init-param>
   <param-name>org.esupportail.filter.authenticationRouter.defaultAuthenticationFilter</param-name>
   <param-value>TRUSTED</param-value>
  </init-param>
{code}\\ 
The following parameter is important and         will often be let to false. If         false, then ONLY ONE filter will be used - the         first one matching the request in the *slide.authenticationRouter.filterList*. If         true then every filter matching the request         will be used.
\\

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 \!
{code}
<init-param>
   <param-name>org.esupportail.filter.authenticationRouter.enableCascading</param-name>
   <param-value>false</param-value>
  </init-param>
{code}

h3. Selection criteria for each authentication filter

\\

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).\\

{code}
<!-- LDAP -->
  <init-param>
   <param-name>org.esupportail.filter.authenticationRouter.allowClientIPLDAP</param-name>
   <param-value></param-value>
  </init-param>
  <init-param>
   <param-name>org.esupportail.filter.authenticationRouter.useSecureRequestLDAP</param-name>
   <param-value></param-value>
  </init-param>
  <init-param>
   <param-name>org.esupportail.filter.authenticationRouter.agentLDAP</param-name>
   <param-value></param-value>
  </init-param>
  <init-param>
   <param-name>org.esupportail.filter.authenticationRouter.httpRequestParameterLDAP</param-name>
   <param-value></param-value>
  </init-param>
  <init-param>
   <param-name>org.esupportail.filter.authenticationRouter.destinationHostLDAP</param-name>
   <param-value></param-value>
  </init-param>
{code}\\
\\
{info}
A filter is selected by the router if each criterion matches             the request.
{info}
Let's have a look on each criterion in more details.

allowClientIP[FilterName] : 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].
{code}
<!-- TRUSTED -->
 <init-param>
   <param-name>org.esupportail.filter.authenticationRouter.allowClientIPTRUSTED</param-name>
   <param-value>129.20.129.12 129.20.129.13</param-value>
  </init-param>
{code}
useSecureRequest[FilterName] : if         true then only HTTPS requests will be forwarded         to the filter [FilterName].\\

{code}
<init-param>
   <param-name>org.esupportail.filter.authenticationRouter.useSecureRequestTRUSTED</param-name>
   <param-value>false</param-value>
  </init-param>
{code}\\ 
agent[FilterName] : 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... - \*Regular
expressions are accepted*.
\\ \\
{code}
<init-param>
   <param-name>org.esupportail.filter.authenticationRouter.agentTRUSTED</param-name>
   <param-value>*mozilla*</param-value>
  </init-param>
{code}\\ 
httpRequestParameter[FilterName] : if empty         then there is no restriction else only request with the given         parameters will be forwarded to the given filter (here TRUSTED).         \*Regular expressions are
accepted*.
\\
{code}
<init-param>
   <param-name>org.esupportail.filter.authenticationRouter.httpRequestParameterTRUSTED</param-name>
   <param-value>auth=trusted authentication=trusted mode*=*secure*</param-value>
  </init-param>
{code}
destinationHost[FilterName] : if empty then         there is no restriction else only request with the given destination         hosts will be forwarded to the given filter (here TRUSTED). \*Regular expressions are
accepted*.
\\
{code}
<init-param>
   <param-name>org.esupportail.filter.authenticationRouter.destinationHostTRUSTED</param-name>
   <param-value>webdav-restricted.univ-rennes1.fr webdav-restricted2.univ-rennes1.fr *.univ-valenciennes.fr</param-value>
  </init-param>
{code}\\
\\

h2. The LDAP authentication filter

\\

Processes an LDAP authentication.
{code}
<filter>
{code}
Filter name and class - you DO NOT have to modify these values
\\
{code}
<filter-name>LDAP</filter-name>
  <filter-class>org.esupportail.filter.LDAPFilter.LDAPFilter</filter-class>
{code}\\ 
Let the following parameter to       true.
\\ \\
{code}
<init-param>
   <param-name>org.esupportail.filter.LDAPFilter.useAuthenticationRouter</param-name>
   <param-value>true</param-value>
  </init-param>
{code}\\ 
LDAP directory URL's (the alternate URL is optionnal - usefull if       the first directory does not work)
\\ \\
{code}
<init-param>
   <param-name>org.esupportail.filter.LDAPFilter.connectionURL</param-name>
   <param-value>ldap://myLdap.univ.fr:389</param-value>
  </init-param>
  <init-param>
   <param-name>org.esupportail.filter.LDAPFilter.alternateURL</param-name>
   <param-value>ldap://myLdap2.univ.fr:389</param-value>
  </init-param>
{code}\\ 
Bind type = searchbind or fastbind
\\
* searchbind : The filter will first try to find the connected             user, using the given *base DN*, *scope* and *filter* \- and then will execute a bind             request.
* fastbind : The filter will try to bind with the given *pattern*
{code}
<init-param>
   <param-name>org.esupportail.filter.LDAPFilter.bindType</param-name>
   <param-value>SEARCHBIND</param-value> <!-- FASTBIND -->
  </init-param>
{code}

fastBindUserPattern : Pattern used to build a DN to bind. The syntax is uniqueAttributeEqualsToLogin={0},baseDN

org{code}
  <init-param>
   <param-name>org.esupportail.filter.LDAPFilter.fastBindUserPattern

uidfastBindUserPattern</param-name>
   <param-value>uid={0}
,ou=people,dc=univ,dc=fr</param-value>
  </init-param>
{code}
\\

The following attributes are optionnals and specify the credential       to connect to the LDAP if needed.
{code}
<init-param>
<param-name>org.esupportail.filter.LDAPFilter.searchBindConnectionName</param-name>
<param-value>LDAPMaster</param-value>
</init-param>
<init-param>
<param-name>org.esupportail.filter.LDAPFilter.searchBindConnectionPassword</param-name>
<param-value>whatACoolWebDAVServer\!</param-value>
</init-param>
{code}
The tree last atributes are classical LDAP configuration       parameters - you won't have any difficulties to understand them. ;-)
{code}
<init-param>
<param-name>org.esupportail.filter.LDAPFilter.searchBindBaseDN</param-name>
<param-value>ou=people,dc=univ,dc=fr</param-value>
</init-param>
<init-param>
<param-name>org.esupportail.filter.LDAPFilter.searchBindScope</param-name>
<param-value>SUBTREE_SCOPE</param-value> <\!-\- SUBTREE_SCOPE \| ONELEVEL_SCOPE \| OBJECT_SCOPE -->
</init-param>
<init-param>
<param-name>org.esupportail.filter.LDAPFilter.searchBindFilter</param-name>
<param-value>uid=
{0}
</param-value>
</init-param>
</filter>
\\
{code}

h2. The TRUSTED authentication filter

\\
Processes a TRUSTED authentication. The easiest filter to       configure.
{code}
<filter>
{code}
Filter name and class - you DO NOT have to modify these values
{code}
<filter-name>TRUSTED</filter-name>
<filter-class>org.esupportail.filter.trustedFilter.TrustedFilter</filter-class>
{code}
Let the following parameter to true.
{code}
<init-param>
<param-name>org.esupportail.filter.trustedFilter.useAuthenticationRouter</param-name>
<param-value>true</param-value>
</init-param>
{code}
Trusted password
{code}
<init-param>
<param-name>org.esupportail.filter.trustedFilter.trustedPassword</param-name>
<param-value>XXXXXXXXXX</param-value>
</init-param>
{code}
*Optionnal* allowed user list - Let       it empty for no user restriction.
{code}
<init-param>
<param-name>org.esupportail.filter.trustedFilter.trustedUsers</param-name>
<param-value>tbellemb:bourges:masterYoda</param-value>
</init-param>
</filter>
{code}

h2. The UNAUTHENTICATED authentication filter

\\
There is no entry for this filter in the       web.xml file because this filter... does not exist       \!

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.

h2. The SHIB authentication filter (only on the v5.0 and
      
upper)
\\
Processes an Shibboleth authentication.
{code}
<filter>
{code}
Filter name and class - you DO NOT have to modify these       values
{code}
<filter-name>SHIB</filter-name>
<filter-class>org.esupportail.filter.shibFilter.ShibFilter</filter-class>
{code}
Let the following parameter to       true.
{code}
<init-param>
<param-name>org.esupportail.filter.shibFilter.useAuthenticationRouter</param-name>
<param-value>true</param-value>
</init-param>
{code}
The *slide.shibFilter.localsDomains* attribute is a       regular expression which describe de locals domains
{code}
<init-param>
<param-name>org.esupportail.filter.ShibFilter.localsDomains</param-name>
<param-value>.*@(univ-rennes1\|ensc-rennes\|sciencespo-rennes\|eleves.ensc-rennes\|etudiant.sciencespo-rennes\|etudiant.univ-rennes1).fr</param-value>
</init-param>
{code}
The value of the *slide.shibFilter.localsDomainsAttribute* attribute       is the attribute name which will pick up the remote user
{code}
<init-param>
<param-name>org.esupportail.filter.ShibFilter.localsDomainsAttribute</param-name>
<param-value>REMOTE_USER2</param-value>
</init-param>
{code}
The *slide.shibFilter.remoteUserAttribute* attribute is       the name of the attribute which have the value that will be used to       define the remote user value
{code}
<init-param>
<param-name>org.esupportail.filter.ShibFilter.remoteUserAttribute</param-name>
<param-value>REMOTE_USER2</param-value>
</init-param>
{code}
The *slide.shibFilter.FormatOutOfRemoteUser* attribute       is a regular expression which indicate de format of the value to the       remote user
{code}
<init-param>
<param-name>org.esupportail.filter.ShibFilter.FormatOutOfRemoteUser</param-name>
<param-value>(.*)@.*:</param-value>
</init-param>
{code}
The *slide.shibFilter.RegexpSeparator* attribute is a       separator used in the FormatOutOfRemoteUser regular       expression
{code}
<init-param>
<param-name>org.esupportail.filter.ShibFilter.RegexpSeparator</param-name>
<param-value>:</param-value>
</init-param>
{code}
The \*slide.shibFilter.remoteUserAttributeOut
      \*attribute is the name of the attribute that store the remote       user value
{code}
<init-param>
<param-name>org.esupportail.filter.ShibFilter.remoteUserAttributeOut</param-name>
<param-value>REMOTE_USER</param-value>
</init-param>
{code}
The parameter *slide.shibFilter.remoteUserAttributeOutSessionOrHeader*       allow to choose between the session attributes and the request       attributes
{code}
<init-param>
<param-name>org.esupportail.filter.ShibFilter.remoteUserAttributeOutSessionOrHeader</param-name>
<param-value>session</param-value>
</init-param>
{code}
The *slide.shibFilter.shibAttributePrefix* attribute is       the prefix of the shibboleth attributes
{code}
<init-param>
<param-name>org.esupportail.filter.ShibFilter.shibAttributePrefix</param-name>
<param-value>Shib</param-value>
</init-param>
{code}
The following parameter indicate if we put the shibboleth       attributes in the session or not
{code}
<init-param>
<param-name>org.esupportail.filter.ShibFilter.shibAttributesInSession</param-name>
<param-value>true</param-value>
</init-param>

</filter>
{code}

h2. The RedirectFilter (only on the v5.1 and upper)

\\
The RedirectFilter is a filter which enable to redirect an url       into another.
{code}
<filter>
{code}
Filter name and class - you DO NOT have to modify these       values
{code}
<filter-name>REDIRECT</filter-name>
<filter-class>org.esupportail.filter.redirectFilter.RedirectFilter</filter-class>
{code}
The *slide.redirectFilter.DestinationHostTrigger*       attribute is the host name on which the RedirectFilter must be       executed
{code}
<init-param>
<param-name>org.esupportail.filter.redirectFilter.DestinationHostTrigger</param-name>
<param-value>[slide.redirectFilter.DestinationHostTrigger]</param-value>
</init-param>
{code}
The slide.redirectFilter.DestinationHost attribute is the host       name which must used for an indentification
{code}
<init-param>
<param-name>org.esupportail.filter.redirectFilter.DestinationHost</param-name>
<param-value>[slide.redirectFilter.DestinationHost]</param-value>
</init-param>

</filter>
{code}
{code}

{code}