Authentication Framework

The central point for building a web application is authentication. The Cocoon authentication package is a flexible module for authentication and user management. A user can be legitimated using any information available via any source, e.g. a database or LDAP. With this mechanism it is very easy and fast to use an exisiting user management/authentication system.

The authentication Framework adds some actions to the sitemap: the auth-protect action, the auth-login action, the auth-logout action and the auth-loggedIn action. The authentication-manager gets the configuration for the authentication framework and the actions controle the pipelines. The auth-login and the auth-logout action control the authentication whereas the auth-loggedIn action controls the application flow.

The use of the authentication framework and its components is described in the following chapters.

One feature of the framework is the user authentication. A document can be accessible for everyone or it can be protected using this framework. The process of requesting a document can be described as follows:

This process is only one example for a use-case of the framework. It can be configured for any authentication scheme. All resources are freely configurable.

The basic object for authentication is the authentication handler. It controlles the access to the resources. Each resource in the sitemap can be related to exactly one authentication handler. All resources belonging to the same handler are protected in the same way. If a user has access to the handler, the user has the same access rights for all resouces of this handler.

Using a unique name for each handler (only alphabetical characters and digits are allowed for the handler name), the framework manages different handlers. So various parts of the sitemap can be protected in different ways. A document can be protected by calling this handler using the auth-protect action. The "auth-protect" action must be included in the pipeline of the resource. It gets the handler information as a parameter:


	<map:match pattern="protectedresource"> <map:act type="auth-protect"> <map:parameter name="handler" value="unique handler name"/> <map:generate src="source/resource.xml"/> </map:act> ... </map:match>

If the pipeline does not use the "auth-protect" action or the parameter "handler" is missing, the document is accessible by any user.

If the requested document is not accessible for the user, the framework redirects to a special redirect-to document. This document is a mandatory configuration of the authentication handler:

<autentication-manager>
  <handlers>
    <!-- Now follows the handlers configuration -->
    <handler name="unique">
      <redirect-to uri="cocoon://loginpage"/> <!-- The login resource -->
    </handler>
  </handlers>
</autentication-manager>

This redirect-to document is an unprotected document in the sitemap. For tracking which document was requested, the redirect-to document gets the request parameter "resource" with the value. In addition all parameters specified inside the redirect-to tag of the handler configuration are passed to the document.

This redirect-to document can contain a form for the user authentication. This form should invoke the real login document which is described below.

The authentication process is done by the "auth-login" action. The login resource contains this action:

<map:match pattern="login">
  <map:act type="auth-login">
    <map:parameter name="handler" value="unique"/>
    <map:parameter name="parameter_userid" value="{request:name}"/>
    <map:parameter name="parameter_password" value="{request:password}"/>
    <map:redirect-to uri="authentication-successful"/>
  </map:act>
  <!-- authentication failed: -->
  <map:generate src="auth_failed.xml"/>
  <map:transform src="tohtml.xsl"/>
  <map:serialize/>
</map:match>

The auth-login action uses the handler parameter to call the authentication resource of this handler. This authentication resource needs to know the information provided by the user. For each piece of information an own parameter is created which name starts with "parameter_". So in the example above, the authentication resource gets two parameters: userid and password. As the values for these parameters were send by a form they need to be passed on to the authentication resource. If you use "{request:...}" for the value of a parameter, the auth-login action will pass the actual value of that request parameter to the authentication resource (by using the input modules concept of Cocoon).

If the user is not already authenticated with this handler, the framework calls the authentication resource and passes it the parameters. If this authentication is successful, the action returns a map and the sitemap commands inside the map:act are executed. If the authentication fails, these are skipped.

If the authentication is successful, a session object is created on the server (if not already done). If the authentication fails, the error information delivered by the authentication resource is stored into the temporary context (which is named simply 'temp').

The last chapters described the authentication process but left out details about the authentication itself. This chapter closes this gap.

Using this flexible approach nearly any kind of authentication is possible (e.g. database, LDAP). The authentication resource is another mandatory configuration of the authentication handler:

<autentication-manager>
  <handlers>
    <!-- Now follows the handlers configuration -->
    <handler name="unique">
      <!-- The login resource -->
      <redirect-to uri="cocoon:raw://loginpage"/>
      <authentication uri="cocoon:raw://authenticationresource"/>
    </handler>
  </handlers>
</autentication-manager>

If the authentication resource is a sitemap resource or a remote resource, this resource is requested by the framework with the given parameters from the auth-login action (see previous chapter: parameters: userid and password). In addition all parameters inside the authentication tag of the handler configuration are passed to the resource. The response for this resource must contain valid XML conforming to the following scheme:


	<authentication> <ID>value</ID> <role>rolename</role> <!-- optional --> <data> ... resource specific data for the user </data> </authentication>

The framework checks the response of the authentication resource for the given scheme: the root node must be named "authentication" and one child called "ID" must be present. In this case the authentication is successfull and the framework creates an authentication session context and stores the XML inside.

The mandatory information inside this XML scheme, the "ID" tag, is an unique identification for the given user inside the web application. The "role" is optional and can for example be used for categorizing users and displaying different functionality inside the Cocoon portal engine).

Using the "data" node the authentication resource can pass any information of the user into the session object.

If the authentication is not successful, the resource must create an XML with the root node "authentication". In addition a "data" node can be added containing more information about the unsuccessful attempt. This data node is then added inside the "login" tag of the login resource (see previous chapter).

This action logs the user out of the given handler and removes all information about this handler stored in the session.

The common solution for the framework and subsitemaps is to define the handler (in the main sitemap. The documents in the subsitemap are then simply protected in the same way as if the action were declared in the main sitemap. This makes moving resources from one sitemap to the other very simple.

However, there is one drawback with this solution. After you have started your server, make sure that first a resource using the framework from the main sitemap is invoked, before any of the subsitemap!

The definition of handlers in a sub-sitemap is a TODO and will be available in the next release.

In addition to the authentication the framework manages all kinds of information belonging to the user in XML format. For this reason the framework creates an own session context called "authentication". All information is stored in this context.

The authentication information (the "authentication" scheme retrieved from the authentication resource) is stored in this context, so you can retrieve and change the information using the session transformer and the usual getxml, setxml etc. commands, so we suggest you to read the session context document.


	<session:getxml context="authentication" path="/authentication/ID"/> <!-- Get the ID --> <session:getxml context="authentication" path="/authentication/data/username"/>

The path expression is an absolute XPath-like expression where only concrete nodes and attributes are allowed. The session transformer replaced the tag with the value of the first node found in the context, this can either be text or XML.

Again the path is an absolute XPath-like expression where only concrete nodes and attributes are allowed. If the requested node exists, the framework changes the value of that node. If the node does not exists, the framework adds it to the context with the given value.

A very useful feature for building and maintaining web applications is the application management. It allows to configure different applications and to manage the user data for these applications.

A "authentication" application is related to one authentication handler, so an application is part of the authentication handler configuration:

<autentication-manager>
    <handlers>
        <handler name="unique">
             ....redirect-to/authentication configuration
             <applications> <!-- the applications for this handler -->
                 <application name="unique">
                     <load uri="loadapp"/> <!-- optional -->
                     <save uri="saveapp"/> <!-- optional -->
                 </application>
             </applications>
        </handler>
    </handlers>
</autentication-manager>

A configuration for an application consists of a unique name (only alphabetical characters and digits are allowed for the application name) and optional load and save resources. The application configuration can contain application specific configuration values for the various parts of the application, e.g. information for a portal.

On a successful authentication the framework invokes for each application of the handler the load resource (if present). The content or result of the load resource is stored into the session context.

The user does not always visit all sides or all applications at once. So it is not necessary to load all applications in advance when not all information is needed. Each application can specify if the data is loaded on successful authentication or the first time needed:

The load resource gets several parameters: all values of the subnodes of the "authentication" node from the authentication context (e.g. ID, role etc.) and the parameter "application" with the unique name of the application. This unique name must not contain one of the characters '_', ':' or '/'.

In addition the load and save resource get all parameters specified inside the load / save tag of the handler configuration.

For managing the application the framework needs to know to which application a resource belongs. So in addition to the handler parameter the auth-protect action gets the application name as a second parameter:

<map:match pattern="protectedresource">
  <map:action type="auth-protect">
    <map:parameter name="handler" value="unique handler name"/>
    <map:parameter name="application" value="unique application name"/>
    
    <map:generate src="source/resource.xml"/>
            ...
  </map:action>
</map:match>

With this mechanism each application resource can easily access its and only its information. If a resource has no "application" parameter it can not access information of any application.

Analogue to the access of the authentication data a resource can access its application data:


	<session:getxml context="authentication" path="/application/username"/> <session:setxml context="authentication" path="/application/shoppingcart"><item1/><item2/></session:setxml>

The path underlies the same restrictions and rules as always, but it has to start with "/application/".

In addition to the application management the framework offers a facility called module management. It enhances the application management by the possibility to configure components for the application. For example the Cocoon portal engine needs information about where the portal profile for the user is retrieved from, where the layout is stored etc. Now each portal needs this information. Assuming that a portal is an application each application needs this information. As only the portal engine itself knows what information it needs, the module management is a standarized way for configuring such components.

<autentication-manager>
  <handlers>
    <handler name="unique">
      ....redirect-to/authentication configuration
      <applications>  <!-- the applications for this handler -->
        <application name="unique">
          ...
          <configuration name="portal">
            ...portal configuration
          </configuration>
        </application>
      </applications>
    </handler>
  </handlers>
</autentication-manager>

So whenever the portal engine is asked to build the portal it can easily retrieve its configuration from the current application by getting the module configuration named "portal".

Using the framework it is possible to add new roles to the system and to add new users. For this purpose, there are several optional entries for the authentication handler which provide the needed functionality:

<autentication-manager>
  <handlers>
    <handler name="unique">
             ...redirect-to/authentication configuration...

      <!-- Optional resource for loading user information -->
      <load-users uri="cocoon:raw://financeresource-sunrise-loaduser"/>

      <!-- Optional resource for loading roles information-->
      <load-roles uri="cocoon:raw://financeresource-sunrise-roles"/>

      <!-- Optional resource for creating a new user -->
      <new-user uri="cocoon:raw://financeresource-sunrise-newuser"/>

      <!-- Optional resource for creating a new role -->
      <new-role uri="cocoon:raw://financeresource-sunrise-newrole"/>

      <!-- Optional resource for changing user information -->
      <change-user uri="cocoon:raw://financeresource-sunrise-newuser"/>

      <!-- Optional resource for deleting a role -->
      <delete-role uri="cocoon:raw://financeresource-sunrise-delrole"/>

      <!-- Optional resource for deleting a user-->
      <delete-user uri="cocoon:raw://financeresource-sunrise-deluser"/>
    </handler>
  </handlers>
</autentication-manager>

The entries are described in the following subchapters. All tags can have additional parameter definitions which are passed to the given resource, e.g:


	<!-- Optional resource for deleting a user--> <delete-user uri="cocoon:raw://financeresource-sunrise-deluser"> <connection>database</connection> <url>db:usertable</url> </delete-user>

The load-roles resource is invoked from the framework whenever it needs information about the available roles. This resource gets the parameter "type" with the value "roles" and should deliver an XML schema with the root node "roles" and for each role a subelement "role" with a text child of the rolename:

The load-users resource is called whenever information about the available users is needed. There are three different uses of this resource:


	<users> <user> <ID>authentication ID</ID> <role>rolename</role> <data> ... application specific data ... </data> </user> <user> ... </user> ... </users>

The new-role resource creates a new role in the system. It gets the parameters "type" with the value "role" and "role" with the new rolename.

The new-user resource creates a new user with a role. It gets the parameters "type" with the value "user", "role" with the rolename and "ID" with the new ID for this user.

The change-user resources changes information of a user. It gets the parameters "type" with the value "user", "role" with the rolename and "ID" with the ID of the user. In addition all - application specific - information of this user is send as parameters.

The delete-user resource should delete a user. It gets the parameters "type" with the value "user", "role" with the rolename and "ID" with the ID of the user.

The delete-role resources deletes a role. It gets the parameters "type" with the value "role" and "role" with the rolename .

<autentication-manager>
  <handlers>
    <handler name="unique">
      <!-- The redirect-to resource -->
      <redirect-to uri="cocoon:raw://loginpage"/>
      <!-- Authentication resource -->
      <authentication uri="cocoon:raw://authenticationresource"/>

      <load uri="cocoon:raw://authenticationsaveresource">
        <!-- optional parameters -->
      </load>
      <!-- optional save resource -->
      <save uri="cocoon:raw://authenticationsaveresource">
        <!-- optional parameters -->
      </save>

      <applications>
        <!-- the applications for this handler -->
        <application name="unique">

          <!-- Loading/Saving -->
          <load uri="cocoon:raw://loadapp">
            <!-- optional -->
            <!-- optional parameters -->
          </load>
          <save uri="cocoon:raw://saveapp">
            <!-- optional -->
            <!-- optional parameters -->
          </save>
          <!-- module configurations: -->

          <configuration name="portal">
            ...portal configuration
          </configuration>
        </application>
      </applications>

    </handler>
  </handlers>
</autentication-manager>

As explained in the previous chapters, the framework uses the auth-protect action for authentication and protecting documents. This chapter shows some common used pipeline patterns for using this framework.

For protecting a document with an authentication handler only the auth-protect action with the parameter configuration for the handler is required.

<map:match pattern="protected">
  <map:act type="auth-protect">  <!-- protect the resource -->
    <map:parameter name="handler" value="myhandler"/>

    <map:generate src="resource.xml"/>
    <map:transform src="toHTML"/>
    <map:serialize/>
  </map:act>
</map:match>

It is very important that the auth-protect action wrapps the real pipeline, as the pipeline is only invoked if the action grants access. The matching must be done before the action is checked as the action performs a redirect for this document.

Often you want to protect a bunch of documents in the same way. One solution is to use the single protected document pattern for each document. With the multiple protected document pattern you only have to use the action once for all documents and not within each document pipeline.

<map:match pattern="protected-*">
  <map:act type="auth-protect"> <!-- protect the resource -->
    <map:parameter name="handler" value="myhandler"/>

    <map:match pattern="protected-first">
      <map:generate src="resource1.xml"/>
      <map:transform src="toHTML"/>
      <map:serialize/>
    </map:match>
        ....
    <map:match pattern="protected-second">
      <map:generate src="resource2.xml"/>
      <map:transform src="toHTML"/>
      <map:serialize/>
    </map:match>
  
  </map:act>
</map:match>

Very important - as explained with the single document pattern - is the leading match before the action is performed. The second match is required to check which pipeline to use.

If you want to create documents which behave different wheather you are logged in or not, the auth-loggedIn action is the component to controll your application flow. This action checks if the user is authenticated for a given handler and calls all sitemap components inside the act tag.

<map:match pattern="startpage">

  <map:act type="auth-loggedIn">  <!-- check authentication -->
    <map:parameter name="handler" value="myhandler"/>

    <map:redirect-to uri="loggedInStartPage"/>
  </map:act>

  <map:generate src="startpage.xml"/>
  <map:transform src="toHTML"/>
  <map:serialize/>
</map:match>

In the example above, if the user is already logged he is redirected to the loggedInStartPage document. If he is not logged in for the given handler, the usual start page is generated.

Both actions, the auth-protect and the auth-loggedIn action return - if the user is logged in for the given handler - all values from the context to the sitemap, e.g. ID, role etc. These values can be used within the other components:

<map:match pattern"protected">
  <map:act type="auth-protect">  <!-- protect the resource -->
    <map:parameter name="handler" value="myhandler"/>

    <!-- Append the ID of the user to the file name -->
    <map:generate src="resource_{ID}.xml"/>
    <map:transform src="toHTML"/>
    <map:serialize/>

  </map:act>
</map:match>

But the auth-loggedIn action does not give the included pipeline access to the authentication context belonging to the handler. If you want this, you have to nest the auth-protect action inside!

<map:match pattern"start">

  <map:act type="auth-loggedIn">  <!-- check authentication -->
    <map:parameter name="handler" value="myhandler"/>

    <map:act type="auth-protect">  <!-- give access to the context -->
      <map:parameter name="handler" value="myhandler"/>

      <map:generate src="getinfofromcontext.xml"/>
      <map:transform src="session"/>
      <map:transform src="toHTML"/>
      <map:serialize/>
    </map:act>
  </map:act>

</map:match>