Google Git
Sign in
apache / cocoon / 19fa7c660808d288d1d6231525a957b07558e5b6 / . / non-releases / trunk_before_flattening / src / documentation / src / content / xdocs / c21-block-authentication-fw-authentication / content_en.html
blob: 6c84fbaffb21a956fd06e560d62968ee2016b1a0 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Authentication Framework</title>
<link href="http://purl.org/DC/elements/1.0/" rel="schema.DC">
<meta content="Carsten Ziegeler" name="DC.Creator">
</head>
<body>
<h1>Introduction</h1>
<p>One central point in building a web application is authentication and authorization. The Cocoon
authentication framework is a flexible module for authentication, authorization and user management.
A user can be legitimated using any information available via any source, e.g. an existing database,
LDAP or the file system. With this mechanism it is very easy to use an exisiting user
management/authentication system within Cocoon.</p>
<p>The basic concept of the authentication framework is to protect documents generated by Cocoon.
By document we refer to the result of a request to Cocoon, this can either be the result
of a pipeline or of a reader defined in the sitemap.</p>
<p>A document is protected by a so called (authentication) handler. A document is associated to a
defined handler to be protected. A user can only request this document if he is authenticated
against this handler.</p>
<p>A handler can be used to protect several documents in the same way. If a user is authenticated
he can access all these documents. It is possible to use different handlers, to product documents
in different ways.</p>
<p>The use of the authentication framework and its components is described in the following
chapters.</p>
<div class="note">As you will see, the user management of the authentication framework is very flexible.
You can design your application without taking into account, which backend is used for the
user management. This can be the file-system, a SQL database, an XML database, a LDAP directory,
just anything. Simply by developing the <em>authentication resource</em>, you can connect to any
system. And another advantage is the flexible switching between user databases. You can for example
use the file-system for the development process and switch than later on to a LDAP system on the
production system. This can be done by simply changing the <em>authentication resource</em>. If you
test this resource on your production system, you don't have to test your whole application again.
(Although in general this might be a good idea...).
</div>
<h1>Sitemap-Components</h1>
<p>The authentication Framework adds some actions to the sitemap: the <em>auth-protect</em>
action, the <em>auth-login</em> action, the <em>auth-logout</em> action
and the <em>auth-loggedIn</em> action. The <em>authentication-manager</em> gets
the configuration for the authentication framework and the actions controle the pipelines.
The <em>auth-login</em> and the <em>auth-logout</em> action control the
authentication whereas the <em>auth-loggedIn</em> action controls the application
flow.</p>
<div align="center">
<img class="figure" alt="Overview" src="images/authentication-fw.jpg" height="360" width="480"></div>
<h1>Protecting Documents</h1>
<p>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:</p>
<ol>
<li>The user request a document (original document).
</li>
<li>The authentication framework checks if this document is protected. If no protection
is specified, the response to the request is this original document.
</li>
<li>If the document is protected, the framework checks, if the user is
authenticated to view it.
</li>
<li>If the user is authenticated, the response is the original
document. If not the framework redirects to a special redirect-to document. This
redirect-to document is freely configurable and can for example contain
information about the unauthorized access and in addition a login form.
</li>
<li>Using the login form an authentication resource can be called
with the corresponding user information (e.g. user id and password). This
authentication resource uses the framework for the authentication process.
</li>
<li>In case of a successful authentication the framework can redirect to
the original document (or to any configured start document).
</li>
<li>If the authentication fails another document is invoked by
the framework displaying information to the user.
</li>
</ol>
<p>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.</p>
<h2>The Authentication handler</h2>
<p>The basic object for authentication is the so called (authentication)
handler. It controlles the access to the documents. Each document in the
sitemap can be related to exactly one authentication handler. All documents 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 documents of this
handler.</p>
<p>Each authentication handler needs the following mandatory
configuration:</p>
<ul>
<li>A unique name.
</li>
<li>The authentication resource: A Cocoon pipeline trying to authenticate a user.
(We will see later on, that there are more possibilities than using a pipeline).
</li>
<li>The redirect-to document: This document is displayed when a not
authorized user tries to access a protected document.
</li>
</ul>
<h2>The Configuration of a Handler</h2>
<p>So let's have a look at the configuration. A handler can be configured in the sitemap.
It is a so-called component configuration for the authentication manager. This
configuration takes place in the <em>map:pipelines</em> section of a sitemap:</p>
<pre class="code">
&lt;map:sitemap&gt;
...component definitions...
&lt;map:pipelines&gt;
&lt;map:component-configurations&gt;
&lt;authentication-manager&gt;
&lt;handlers&gt;
&lt;handler name="portalhandler"&gt;
&lt;redirect-to uri="cocoon:/sunspotdemoportal"/&gt;
&lt;authentication uri="cocoon:raw:/sunrise-authuser"/&gt;
&lt;/handler&gt;
&lt;/handlers&gt;
&lt;/authentication-manager&gt;
&lt;/map:component-configurations&gt;
&lt;map:pipeline&gt;
... document pipelines following here:
</pre>
<p>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.
</p>
<p>A handler is inherited to a sub sitemap. Each sub sitemap can define
its own handlers. These handlers are only available to the sub sitemap
(and of course to its sub sitemaps). However, it is not possible to
redefine (overwrite) a previously defined handler in a sub sitemap.</p>
<h2>Protecting Documents</h2>
<p>A document can be protected by associating it to a defined handler.
This is done by using the <em>auth-protect</em> action and the handler parameter:</p>
<pre class="code">&lt;map:match pattern="protectedresource"&gt;
&lt;map:act type="auth-protect"&gt;
&lt;map:parameter name="handler" value="portalhandler"/&gt;
&lt;map:generate src="source/resource.xml"/&gt;
&lt;map:serialize type="xml"/&gt;
&lt;/map:act&gt;
&lt;/map:match&gt;</pre>
<p>If this document is requested, the action checks if the user is authenticated against the
defined handler. If not, the action automatically redirects to the <em>redirect-to</em> document
configured in the handler. (In the example above this is the pipeline defined by <em>cocoon:/sunspotdemoportal</em>.</p>
<p>If the user is authenticated, the commands inside the <em>map:act</em> will be execute and
the user gets the document itself.</p>
<p>So, the <em>auth-protect</em> action must be included in the pipeline of the
document. It gets the handler information as a parameter. If the pipeline does
not use the <em>auth-protect</em> action or the parameter <em>handler</em> is missing,
the document is accessible by any user.</p>
<div class="note">You will see learn later on how to efficiently protect several documents with a handler.</div>
<h2>The redirect-to document</h2>
<p>If the requested document is not accessible to the user, the authentication framework
redirects to the configured <em>redirect-to</em> document. This document is a mandatory
configuration of the authentication handler as we have seen above.</p>
<p>This <em>redirect-to</em> document is an unprotected pipeline in the
sitemap. For tracking which document was originally requested by the user,
the <em>redirect-to</em> pipeline gets the request parameter <em>resource</em>
with that value. In addition all parameters specified inside the <em>redirect-to</em>
tag of the handler configuration are passed to the pipeline as well.</p>
<p>For example, the <em>redirect-to</em> document can contain a form for the user
authentication. This form should invoke the real authentication process that is
described below. However, the document you show when an unauthorized access
is made, can be controlled by you by defining this <em>redirect-to</em>
document.</p>
<h1>Authenticating a User</h1>
<p>Usually, the <em>redirect-to</em> document of a handler contains a form for the user
to authenticate. But of course, you are not limited to this. No matter how the
<em>redirect-to</em> document looks like, the user has "somewhere" the abilitiy
to authenticate, so in most cases the user has a form where he can enter
his information (e.g. user name and password). You have to write a pipeline
presenting this form to the user. When the form is submitted, the authentication
process has to be started inside the authentication framework. As a submit
of a form invokes a request to Cocoon, a pipeline in the sitemap is triggered.
We refer to this pipeline with <em>login pipeline</em>.</p>
<h2>The Login Process</h2>
<p>The authentication process is started by invoking the <em>auth-login</em> action.
So, the <em>login pipeline</em> has to contain this action:</p>
<pre class="code">&lt;map:match pattern="login"&gt;
&lt;map:act type="auth-login"&gt;
&lt;map:parameter name="handler" value="portalhandler"/&gt;
&lt;map:parameter name="parameter_userid" value="{request-param:name}"/&gt;
&lt;map:parameter name="parameter_password" value="{request-param:password}"/&gt;
&lt;map:redirect-to uri="authentication-successful"/&gt;
&lt;/map:act&gt;
&lt;!-- authentication failed: --&gt;
&lt;map:generate src="auth_failed.xml"/&gt;
&lt;map:transform src="tohtml.xsl"/&gt;
&lt;map:serialize/&gt;
&lt;/map:match&gt;</pre>
<p>The <em>auth-login</em> action uses the handler parameter to call the
<em>authentication resource</em> of this handler. This <em>authentication resource</em> needs to
know the information provided by the user, e.g. in the form. For each piece of information an own
parameter is created. The name of this parameter has to start with "parameter_".
So in the example above, the <em>authentication resource</em> gets two parameters: userid and password. As
the values of these parameters were sent by a form they need to be passed on
to the <em>authentication resource</em>. If you use "{request-param:...}" for the value of a
parameter, the <em>auth-login</em> action will pass the actual value of that request
parameter to the <em>authentication resource</em> (by using the input modules concept
of Cocoon).</p>
<div class="note">You might be wondering why we explicitly pass the request parameters on to the
internal pipeline call. Note that the <em>authentication resource</em> of the
portalhandler is defined by <em>cocoon:raw</em>. By using this, no request
parameter of the original request is passed on to the internal pipeline by
default and therefore we have to define them explicitly. If you use
<em>cocoon:</em> then the parameters of the form are by default passed on
to the <em>authentication resource</em> and we could omit the parameter definition
from above. But we feel that it is safer to explicitly define them.</div>
<p>If the user is not already authenticated with this handler, the framework calls
the <em>authentication resource</em> and passes it the parameters. If this
authentication is successful, the action returns a map and the sitemap
commands inside the <em>map:act</em> are executed. A session is created on
the server (if not already done) as well.</p>
<p>If the authentication fails, the action does not deliver a map and
therefore the commands inside the <em>map:act</em> are skipped. The error
information delivered by the <em>authentication resource</em> is stored into the
<em>temporary</em> context. So you can get the information using either the
<em>session transformer</em> or the <em>session-context input module</em>.</p>
<div class="note">As you can see from the example above, you are not limited in defining
the information the user has to provide. This can be either one field, two or
as many fields as you need.</div>
<h2>The authentication resource</h2>
<p>The last chapter described the authentication process but left out
details about the authentication itself. This chapter closes this gap.</p>
<p>The authentication can be done by different components:</p>
<ul>
<li>A sitemap resource (pipeline).
</li>
<li>A distant resource, e.g. requested via HTTP.
</li>
<li>A java class.
</li>
</ul>
<p>The first two are actually similar as in both cases a URI is called. So we
will talk about them in the next chapter. Authentication using a java class
is the topic of the following chapter.</p>
<h3>Using a URI as the authentication resource</h3>
<p>Using this flexible approach nearly any kind of authentication is
possible (e.g. database, LDAP). The <em>authentication resource</em> is another
mandatory configuration of the authentication handler:</p>
<pre class="code">&lt;autentication-manager&gt;
&lt;handlers&gt;
&lt;!-- Now follows the handlers configuration --&gt;
&lt;handler name="portalhandler"&gt;
&lt;!-- The login resource --&gt;
&lt;redirect-to uri="cocoon:/sunspotdemoportal"/&gt;
&lt;authentication uri="cocoon:raw:/sunrise-authuser"/&gt;
&lt;/handler&gt;
&lt;/handlers&gt;
&lt;/autentication-manager&gt;</pre>
<p>If the <em>authentication resource</em> is a sitemap resource or a remote
resource, this resource is requested by the framework with the given parameters from
the <em>auth-login</em> action (see previous chapter). In addition all parameters inside
the <em>authentication</em> tag of the handler configuration are passed to the resource.
The response of this resource must contain valid XML conforming to the following scheme:</p>
<pre class="code">&lt;authentication&gt;
&lt;ID&gt;Unique ID of the user in the system&lt;/ID&gt;
&lt;role&gt;rolename&lt;/role&gt; &lt;!-- optional --&gt;
&lt;data&gt;
Any additional optional information can be supplied here.
This will be stored in the session for later retrieval
&lt;/data&gt;
&lt;/authentication&gt;</pre>
<p>The XML is very simply, only the root element <em>authentication</em> and the <em>ID</em>
element with a valid unique ID for the user in this handler is required. Everything else is optional.
</p>
<p>The framework checks the response of the authentication resource for the
given scheme: the root node must be named <em>authentication</em> and one child called
<em>ID</em> must be present. In this case the authentication is successfull and
the framework creates an authentication session context and stores the XML inside.</p>
<p>The mandatory information inside this XML scheme, the <em>ID</em> tag, is
an unique identification for the given user inside the web application or
more precisly inside this handler. The <em>role</em> is optional and can for example
be used for categorizing users and displaying different functionality inside the Cocoon portal
engine).</p>
<div class="note">As stated, the <em>role</em> element is optional, you can use your own
categorization and exchange it with a <em>roles</em> element or a <em>group</em>
element or leave it out, if you don't need it. In addition you can add any
other element there as well and access the information later on.</div>
<p>Using the <em>data</em> node the <em>authentication resource</em> can pass any
information of the user into the session. From there you can retrieve the
information as long as the session is valid.</p>
<p>If the authentication is not successful, the resource must create
an XML with the root node <em>authentication</em>, but of course without
the <em>ID</em> tag. In addition a <em>data</em> node can be added containing
more information about the unsuccessful attempt. This data
node is then stored into the <em>temporay</em> context (see previous
chapter).</p>
<div class="note">It is advisable to make an internal pipeline for the <em>authentication resource</em>.
An internal pipeline is not directly accessible by a user.</div>
<h3>Using a Java class as the authentication resource</h3>
<p>Using a class is an alternative for using a pipeline.
You can define this class in the handler configuration as an attribute
<em>authenticator</em> of the <em>authentication</em> element, e.g.:</p>
<pre class="code">&lt;autentication-manager&gt;
&lt;handlers&gt;
&lt;!-- Now follows the handlers configuration --&gt;
&lt;handler name="portalhandler"&gt;
&lt;!-- The login resource --&gt;
&lt;redirect-to uri="cocoon:/sunspotdemoportal"/&gt;
&lt;authentication authenticator="mypkg.MyAuthenticator"/&gt;
&lt;/handler&gt;
&lt;/handlers&gt;
&lt;/autentication-manager&gt;</pre>
<p>This class must conform to the <em>Authenticator</em> interface. This
interface provides a method that tries to authenticate a User and
delivers XML that is stored in the session on success. So, the behaviour
is similar to the pipeline.</p>
<h2>Logging out</h2>
<p>The logout process is triggered by the "auth-logout"
action:</p>
<pre class="code">&lt;map:act type="auth-logout"&gt;
&lt;map:parameter name="handler" value="unique"/&gt;
&lt;/map:act&gt;</pre>
<p>This action logs the user out of the given handler and removes all
information about this handler stored in the session.</p>
<h1>User Management</h1>
<p>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 <em>authentication</em>. All information
is stored in this context.</p>
<p>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.</p>
<div class="note">The <em>authentication</em> context is only available to the
<em>session transformer</em> if the pipeline, the transformer is
running in, is associated to the (authentication) handler. Or putting
it in other words: you have to use the <em>auth-project</em> action
in that pipeline. Otherwise the <em>authentication</em> context
is not available.</div>
<h2>Getting information from the context</h2>
<p>Each information from within the context is gettable using an XML
tag:</p>
<pre class="code">&lt;session:getxml context="authentication" path="/authentication/ID"/&gt; &lt;!-- Get the ID --&gt;
&lt;session:getxml context="authentication" path="/authentication/data/username"/&gt;</pre>
<p>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.</p>
<h2>Setting information in the context</h2>
<p>Using another tag information can be stored into the
context:</p>
<pre class="code">&lt;session:setxml context="authentication" path="/authentication/data/usersername"&gt;
Mr. Sunshine
&lt;/session:setxml&gt;</pre>
<p>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.</p>
<p>The tag is removed from the resource.</p>
<h1>Application Management</h1>
<p>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.</p>
<h2>Configuring an Application</h2>
<p>A "authentication" application is related to one authentication handler, so an
application is part of the authentication handler configuration:</p>
<pre class="code">&lt;autentication-manager&gt;
&lt;handlers&gt;
&lt;handler name="unique"&gt;
....redirect-to/authentication configuration
&lt;applications&gt; &lt;!-- the applications for this handler --&gt;
&lt;application name="unique"&gt;
&lt;load uri="loadapp"/&gt; &lt;!-- optional --&gt;
&lt;save uri="saveapp"/&gt; &lt;!-- optional --&gt;
&lt;/application&gt;
&lt;/applications&gt;
&lt;/handler&gt;
&lt;/handlers&gt;
&lt;/autentication-manager&gt;</pre>
<p>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.</p>
<p>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.</p>
<p>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:</p>
<pre class="code">....&lt;application name="unique" loadondemand="true"/&gt;...</pre>
<p>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 '/'.</p>
<p>In addition the load and save resource get all parameters specified
inside the load / save tag of the handler configuration.</p>
<h2>Configuring the resources</h2>
<p>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:</p>
<pre class="code">&lt;map:match pattern="protectedresource"&gt;
&lt;map:action type="auth-protect"&gt;
&lt;map:parameter name="handler" value="unique handler name"/&gt;
&lt;map:parameter name="application" value="unique application name"/&gt;
&lt;map:generate src="source/resource.xml"/&gt;
...
&lt;/map:action&gt;
&lt;/map:match&gt;
</pre>
<p>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.</p>
<h2>Getting, setting and saving application information</h2>
<p>Analogue to the access of the authentication data a resource can
access its application data:</p>
<pre class="code">&lt;session:getxml context="authentication" path="/application/username"/&gt;
&lt;session:setxml context="authentication" path="/application/shoppingcart"&gt;&lt;item1/&gt;&lt;item2/&gt;&lt;/session:setxml&gt;</pre>
<p>The path underlies the same restrictions and rules as always, but
it has to start with "/application/". </p>
<h1>Module Management</h1>
<p>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.</p>
<p>The module configuration is part of the application
configuration:</p>
<pre class="code">&lt;autentication-manager&gt;
&lt;handlers&gt;
&lt;handler name="unique"&gt;
....redirect-to/authentication configuration
&lt;applications&gt; &lt;!-- the applications for this handler --&gt;
&lt;application name="unique"&gt;
...
&lt;configuration name="portal"&gt;
...portal configuration
&lt;/configuration&gt;
&lt;/application&gt;
&lt;/applications&gt;
&lt;/handler&gt;
&lt;/handlers&gt;
&lt;/autentication-manager&gt;</pre>
<p>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".</p>
<h1>User Administration</h1>
<p>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:</p>
<pre class="code">&lt;autentication-manager&gt;
&lt;handlers&gt;
&lt;handler name="unique"&gt;
...redirect-to/authentication configuration...
&lt;!-- Optional resource for loading user information --&gt;
&lt;load-users uri="cocoon:raw://financeresource-sunrise-loaduser"/&gt;
&lt;!-- Optional resource for loading roles information--&gt;
&lt;load-roles uri="cocoon:raw://financeresource-sunrise-roles"/&gt;
&lt;!-- Optional resource for creating a new user --&gt;
&lt;new-user uri="cocoon:raw://financeresource-sunrise-newuser"/&gt;
&lt;!-- Optional resource for creating a new role --&gt;
&lt;new-role uri="cocoon:raw://financeresource-sunrise-newrole"/&gt;
&lt;!-- Optional resource for changing user information --&gt;
&lt;change-user uri="cocoon:raw://financeresource-sunrise-newuser"/&gt;
&lt;!-- Optional resource for deleting a role --&gt;
&lt;delete-role uri="cocoon:raw://financeresource-sunrise-delrole"/&gt;
&lt;!-- Optional resource for deleting a user--&gt;
&lt;delete-user uri="cocoon:raw://financeresource-sunrise-deluser"/&gt;
&lt;/handler&gt;
&lt;/handlers&gt;
&lt;/autentication-manager&gt;</pre>
<p>The entries are described in the following subchapters. All tags can
have additional parameter definitions which are passed to the given resource,
e.g:</p>
<pre class="code">&lt;!-- Optional resource for deleting a user--&gt;
&lt;delete-user uri="cocoon:raw://financeresource-sunrise-deluser"&gt;
&lt;connection&gt;database&lt;/connection&gt;
&lt;url&gt;db:usertable&lt;/url&gt;
&lt;/delete-user&gt;</pre>
<h2>Getting Roles</h2>
<p>The <em>load-roles</em> 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:</p>
<pre class="code">&lt;roles&gt;
&lt;role&gt;admin&lt;/role&gt;
&lt;role&gt;guest&lt;/role&gt;
&lt;role&gt;user&lt;/role&gt;
&lt;/roles&gt;</pre>
<h2>Getting Users</h2>
<p>The <em>load-users</em> resource is called whenever information
about the available users is needed. There are three different uses of this
resource:</p>
<ul>
<li>Loading all users: The resource gets the parameter "type"
with the value "users". It should then deliver all users in the system.
</li>
<li>Loading all users of one role. The resource gets the
parameters "type" with the value "users" and "role" with the rolename.
</li>
<li>Load information of one user. The resource gets the
parameters "type" with the value "user", "role" with the rolename and "ID" with
the authentication ID of the user.
</li>
</ul>
<p>The XML format of the resource should look like the
following:</p>
<pre class="code">&lt;users&gt;
&lt;user&gt;
&lt;ID&gt;authentication ID&lt;/ID&gt;
&lt;role&gt;rolename&lt;/role&gt;
&lt;data&gt;
... application specific data ...
&lt;/data&gt;
&lt;/user&gt;
&lt;user&gt;
...
&lt;/user&gt;
...
&lt;/users&gt;</pre>
<h2>Creating a new role</h2>
<p>The <em>new-role</em> resource creates a new role in the system. It
gets the parameters "type" with the value "role" and "role" with the new
rolename.</p>
<h2>Creating a new user</h2>
<p>The <em>new-user</em> resource creates a new user with a role. It
gets the parameters <em>"type"</em> with the value <em>"user"</em>,
<em>"role"</em> with the rolename and <em>"ID"</em> with the new ID for this
user.</p>
<h2>Changing information of a user</h2>
<p>The <em>change-user</em> 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.</p>
<h2>Delete a user</h2>
<p>The <em>delete-user</em> 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.</p>
<h2>Delete a role</h2>
<p>The <em>delete-role</em> resources deletes a role. It gets the
parameters "type" with the value "role" and "role" with the rolename .</p>
<h1>Configuration Summary</h1>
<p>Here is a brief summary of the authentication handler configuration: </p>
<pre class="code">&lt;autentication-manager&gt;
&lt;handlers&gt;
&lt;handler name="unique"&gt;
&lt;!-- The redirect-to resource --&gt;
&lt;redirect-to uri="cocoon:raw://loginpage"/&gt;
&lt;!-- Authentication resource --&gt;
&lt;authentication uri="cocoon:raw://authenticationresource"/&gt;
&lt;load uri="cocoon:raw://authenticationsaveresource"&gt;
&lt;!-- optional parameters --&gt;
&lt;/load&gt;
&lt;!-- optional save resource --&gt;
&lt;save uri="cocoon:raw://authenticationsaveresource"&gt;
&lt;!-- optional parameters --&gt;
&lt;/save&gt;
&lt;applications&gt;
&lt;!-- the applications for this handler --&gt;
&lt;application name="unique"&gt;
&lt;!-- Loading/Saving --&gt;
&lt;load uri="cocoon:raw://loadapp"&gt;
&lt;!-- optional --&gt;
&lt;!-- optional parameters --&gt;
&lt;/load&gt;
&lt;save uri="cocoon:raw://saveapp"&gt;
&lt;!-- optional --&gt;
&lt;!-- optional parameters --&gt;
&lt;/save&gt;
&lt;!-- module configurations: --&gt;
&lt;configuration name="portal"&gt;
...portal configuration
&lt;/configuration&gt;
&lt;/application&gt;
&lt;/applications&gt;
&lt;/handler&gt;
&lt;/handlers&gt;
&lt;/autentication-manager&gt;</pre>
<h1>Pipeline Patterns</h1>
<p>As explained in the previous chapters, the framework uses the <em>auth-protect</em>
action for authentication and protecting documents. This chapter shows some
common used pipeline patterns for using this framework.</p>
<h2>Single protected document</h2>
<p>For protecting a document with an authentication handler only the <em>auth-protect</em>
action with the parameter configuration for the handler is required.</p>
<p>Pattern:</p>
<ol>
<li>Pipeline matching
</li>
<li>Using the <em>auth-protect</em> action for protecting
</li>
</ol>
<p>Example:</p>
<pre class="code">&lt;map:match pattern="protected"&gt;
&lt;map:act type="auth-protect"&gt; &lt;!-- protect the resource --&gt;
&lt;map:parameter name="handler" value="myhandler"/&gt;
&lt;map:generate src="resource.xml"/&gt;
&lt;map:transform src="toHTML"/&gt;
&lt;map:serialize/&gt;
&lt;/map:act&gt;
&lt;/map:match&gt;</pre>
<p>It is very important that the <em>auth-protect</em> 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.</p>
<h2>Multiple protected documents</h2>
<p>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.</p>
<p>The prerequisite for this is a common matching pattern for the
documents:</p>
<ol>
<li>Pipeline pattern matching
</li>
<li>Using the <em>auth-protect</em> action for protection
</li>
<li>Pipeline matching
</li>
</ol>
<p>Example:</p>
<pre class="code">&lt;map:match pattern="protected-*"&gt;
&lt;map:act type="auth-protect"&gt; &lt;!-- protect the resource --&gt;
&lt;map:parameter name="handler" value="myhandler"/&gt;
&lt;map:match pattern="protected-first"&gt;
&lt;map:generate src="resource1.xml"/&gt;
&lt;map:transform src="toHTML"/&gt;
&lt;map:serialize/&gt;
&lt;/map:match&gt;
....
&lt;map:match pattern="protected-second"&gt;
&lt;map:generate src="resource2.xml"/&gt;
&lt;map:transform src="toHTML"/&gt;
&lt;map:serialize/&gt;
&lt;/map:match&gt;
&lt;/map:act&gt;
&lt;/map:match&gt;</pre>
<p>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.</p>
<h2>Controlling the Application Flow</h2>
<p>If you want to create documents which behave different wheather you
are logged in or not, the <em>auth-loggedIn</em> 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 <em>act</em>
tag.</p>
<pre class="code">&lt;map:match pattern="startpage"&gt;
&lt;map:act type="auth-loggedIn"&gt; &lt;!-- check authentication --&gt;
&lt;map:parameter name="handler" value="myhandler"/&gt;
&lt;map:redirect-to uri="loggedInStartPage"/&gt;
&lt;/map:act&gt;
&lt;map:generate src="startpage.xml"/&gt;
&lt;map:transform src="toHTML"/&gt;
&lt;map:serialize/&gt;
&lt;/map:match&gt;</pre>
<p>In the example above, if the user is already logged he is
redirected to the <em>loggedInStartPage</em> document. If he is not logged in
for the given handler, the usual start page is generated.</p>
<p>The <em>auth-protect</em> action returns - 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:</p>
<pre class="code">&lt;map:match pattern"protected"&gt;
&lt;map:act type="auth-protect"&gt; &lt;!-- protect the resource --&gt;
&lt;map:parameter name="handler" value="myhandler"/&gt;
&lt;!-- Append the ID of the user to the file name --&gt;
&lt;map:generate src="resource_{ID}.xml"/&gt;
&lt;map:transform src="toHTML"/&gt;
&lt;map:serialize/&gt;
&lt;/map:act&gt;
&lt;/map:match&gt;</pre>
<p>But the <em>auth-loggedIn</em> 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 <em>auth-protect</em> action inside!</p>
<pre class="code">&lt;map:match pattern"start"&gt;
&lt;map:act type="auth-loggedIn"&gt; &lt;!-- check authentication --&gt;
&lt;map:parameter name="handler" value="myhandler"/&gt;
&lt;map:act type="auth-protect"&gt; &lt;!-- give access to the context --&gt;
&lt;map:parameter name="handler" value="myhandler"/&gt;
&lt;map:generate src="getinfofromcontext.xml"/&gt;
&lt;map:transform type="session"/&gt;
&lt;map:transform src="toHTML"/&gt;
&lt;map:serialize/&gt;
&lt;/map:act&gt;
&lt;/map:act&gt;
&lt;/map:match&gt;</pre>
<h2>Session Handling</h2>
<p>If a user is authenticated the user has a session. However, care has to be taken that
the session tracking works, which means that Cocoon can detect that a follow up request
of the user belongs to the same session.</p>
<p>The easiest way is to use the <em>encodeURL</em> transformer as the last transformation
step in your pipeline. For more information about session handling, have a look in
the <a href="session.html">chapter about sessions</a>.</p>
</body>
</html>