cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ron Wheeler <>
Subject [Fwd: Re: Cocoon - modified authentication.xml]
Date Mon, 08 Aug 2005 02:39:04 GMT
This is a post that I sent to Carsten Ziegeler. I should probably been 
directed to this list.
I includes my modified version of the documentation fragment 

I am a newbee at Cocoon so my changes need to be carefully checked.
I hope that my background and inexperience will result in a document 
that is clearer to the intended audience.

I am working through the tutorial and revising the 
tutorial-develop-webapp.xml as I test the tutorial steps.
I have found some pretty big holes that makes me think that the tutorial 
depends on some files and file placemets that have changed in the 2.1.7 
distribution. I am doing my best to find the missing pieces and guess 
what the filenames should be for the files that are being created.

I will forward a draft as soon as I get to the end. You might also get 
some questions before that but so far I have been able to figure out 
each problem as it came up.


-------- Original Message --------
Subject: 	Re: Cocoon - modified authentication.xml
Date: 	Fri, 05 Aug 2005 09:58:14 -0400
From: 	Ron Wheeler <>
Organization: 	Artifact

around 507
     <s2 title="Getting 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 sub-element "role" 
with a text child
          of the rolename:</p>

Doesn't it return an XML datastructure rather than a schema.

This brings up the question about various schemas for the XML 
datastructures  for the user defined resources in this section.
Are there schemas that describe the structures that the user defined 
resources must pass back to the framework.

Ron wrote:

>Hi Ron,
>many thanks for your work, really appreciated! Obviously, I'm not a native
>speaker therefore I'm really happy whenever someone corrects my mistakes!
>Could you please send your final version to the developer mailing list
>( This is the official way and we want to ensure
>that all contributions go this way, so everyone can keep track of them. I
>will happily pick it up from there and apply it asap.
>Now, for your questions:
>Unclear concepts:
>>"own parameter"??? around line 203 -  For each piece of information an
>>own parameter is created.
>Perhaps a "separate parameter" is better? Actually, you have to create a
>for each and every piece of information you need for authentication.
>Usually these
>are the request parameters comming from the form. So if you have a form
>with user name
>and password, you have to create two parameters here. But you could also
>add some other
>information as the ip address of the client etc.
>>around line367   Not sure what this means in this context  " <p>The tag
>>is removed from the resource.</p>"
>The XML containing the tag - or element - (session:setxml) is passed (as
>SAX events) through the pipeline.
>When the transformer receives this tag the transformer processed the tag
>(or command) in the
>way described in the paragraph lin 367. The tag is then removed by the
>which means the transformer does not pass this tag to the next component in
>the pipeline.
>>398 "sides" - do you mean "sites"
>>563  This makes no reference to changing anything and only talks about
>>sending information except in the name. What does it do? It talks about
>>getting things and things being "sent".
>>    <s2 title="Changing information of a user">
>>       <p>The <em>change-user</em> resources changes information of a
>>         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
>>         information of this user is sent as parameters.</p>
>>    </s2>
>Ah ok, this chapter describes resources (which actually are pipelines) that
>are invoked by
>the authentication framework. So, when the user changes the information,
>authentication framework calls this "change-user" resource (or pipeline)
>adds the parameters (type, role and ID). It's up to the developer to
>develop this
>resource (pipeline) and do whatever appropriate. For example, updating the
>with the new information.
>>569 changed "should" to "will" but it has the same problem as "Changing
>>information of a user" in that it talks about getting things not
>>deleting except in the title and first sentence. What does it do? How do
>>you invoke it?
>>   <s2 title="Delete a user">
>>       <p>The <em>delete-user</em> resource will delete a user. It gets
>>         parameters "type" with the value "user", "role" with the
>>rolename and "ID" with
>>         the ID of the user.</p>
>>    </s2>
>Yes, actually, it's the same. So, it's the task of the web developer to
>define all these pipelines
>and then either the authentication framework or youself call this pipeline.
>For example, if you provide your own delete user functionality, you can
>call this resource, provide the required parameters and it will delete the
>Now, actually these features, like change user, delete user etc., are
>currently not really used. They are there to provide "standardized hooks"
>for your own application to perform these tasks if required.
>I hope this makes things a little bit more clear. If you need more
>information, just ask :)
>Thanks for your work!
>Have a nice weekend
>Freundliche Grüße / With kind regards
>Carsten Ziegeler
>Klingenderstrasse 5
>D 33100 Paderborn
>voice  +49 5251/1581-49
>fax      +49 5251/1581-71
>                      Ron Wheeler                                                                                                                     
>                      <rwheeler@artifact-so         An:                                                                     
>            >                   Kopie:                                                                                            
>                                                    Thema:   Cocoon - modified authentication.xml                                                     
>                      01.08.2005 16:09                                                                                                                
>                      Bitte antworten an                                                                                                              
>                      rwheeler                                                                                                                        
>I started reading the authentication documentation and came across a few
>things that made it harder to read than it needed to be so I did a
>cleanup on the English.
>I have attached a modified version of the authentication.xml file.
>I tried to make it more readable and I fixed some spelling and grammer
>I found the following bits and pieces that where not suffieciently clear
>to me that I felt comfortable changing them.
>If you can tell me what you meant here, I will try to finish my editing.
>I am not a Cocoon expert so you may want to check what I have done but I
>was pretty careful not to change things where I was not able to figure
>out the original authors's intent.
>I hope that this contributes in a small way to the success of Cocoon.
>Unclear concepts:
>"own parameter"??? around line 203 -  For each piece of information an
>own parameter is created.
>around line367   Not sure what this means in this context  " <p>The tag
>is removed from the resource.</p>"
>398 "sides" - do you mean "sites"
>563  This makes no reference to changing anything and only talks about
>sending information except in the name. What does it do? It talks about
>getting things and things being "sent".
>     <s2 title="Changing information of a user">
>        <p>The <em>change-user</em> resources changes information of a
>          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
>          information of this user is sent as parameters.</p>
>     </s2>
>569 changed "should" to "will" but it has the same problem as "Changing
>information of a user" in that it talks about getting things not
>deleting except in the title and first sentence. What does it do? How do
>you invoke it?
>     <s2 title="Delete a user">
>        <p>The <em>delete-user</em> resource will delete a user. It gets
>          parameters "type" with the value "user", "role" with the
>rolename and "ID" with
>          the ID of the user.</p>
>     </s2>
><?xml version="1.0" encoding="UTF-8"?>
>  Copyright 1999-2004 The Apache Software Foundation
>  Licensed under
>the Apache License, Version 2.0 (the "License");
>  you may not use this file
>except in compliance with the License.
>  You may obtain a copy of the
>License at
>  Unless required
>by applicable law or agreed to in writing, software
>  distributed under the
>License is distributed on an "AS IS" BASIS,
>CONDITIONS OF ANY KIND, either express or implied.
>  See the License for the
>specific language governing permissions and
>  limitations under the License.
><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
>    <header>
>        <title>Authentication Framework</title>
>        <authors>
>            <person name="Carsten Ziegeler" email=""/>
>        </authors>
>    </header>
>    <body>
>  <s1 title="Introduction">
>     <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 authentication handler. A document is
>associated with a
>       defined handler to provides the protection. A user's request for a
>document will only succeed if the handler
>                signals that the user passes authentication.</p>
>     <p>It is possible to use different handlers to protect different
>documents in different ways.</p>
>     <p>The use of the authentication framework and its components is
>described in the following
>        chapters.</p>
>     <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. The backend can be the file-system, a SQL database,
>an XML database, a LDAP directory or
>       just about anything. You can connect to any system simply by
>developing the <em>authentication resource</em>.
>                Another advantage is the flexible switching between user
>databases. For example, you can use the file-system for the development
>process and later on, switch to a LDAP system on the production system.
>This is done by 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...).
>     </note>
>  </s1>
>  <s1 title="Sitemap-Components">
>     <p>The authentication Framework adds some actions to the sitemap: the
>        action, the <em>auth-login</em> action, the <em>auth-logout</em>
>        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
>        authentication whereas the <em>auth-loggedIn</em> action controls
>the application
>        flow.</p>
>    <figure src="images/authentication-fw.jpg" alt="Overview"
>              width="480" height="360"/>
>  </s1>
>  <s1 title="Protecting Documents">
>     <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 requests 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 the original
>        </li>
>        <li>If the document is protected, the framework checks, if the user
>          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 could, for
>example, contain
>          information about the unauthorized access and 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
>        </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.
>        can be configured for any authentication scheme. All resources are
>        configurable.</p>
>     <s2 title="The Authentication handler">
>        <p>The basic object for authentication is the authentication
>                           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
>associated with 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 used 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
>user fails authentication.
>          </li>
>        </ul>
>     </s2>
>     <s2 title="The Configuration of a Handler">
>        <p>So let's have a look at the configuration. A handler is
>configured in the sitemap using a <em>component configuration<em> for the
>authentication manager.
>                         This configuration is specified in the
><em>map:pipelines</em> section of a sitemap:</p>
>    ...component definitions...
>  &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;
>   ... document pipelines following here:
>        <p>Using a unique name for each handler (only alphabetical
>          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
>           its own handlers. These handlers are only available to the sub
>           (and of course to its sub sitemaps). However, it is not possible
>           redefine (overwrite) a previously defined handler in a sub
>     </s2>
>     <s2 title="Protecting Documents">
>        <p>A document is protected by associating it with a defined
>        This is done by using the <em>auth-protect</em> action and the
>handler parameter:</p>
><source>&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;
>        <p>If this document is requested, the action checks that the
>defined handler successfully authenticates the user.
>                         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>
>        <note>You will see learn later on how to efficiently protect
>several documents with a handler.</note>
>     </s2>
>     <s2 title="The redirect-to document">
>        <p>If the requested document is not accessible by the user, the
>authentication framework
>          redirects to the configured <em>redirect-to</em> document. This
>document is a mandatory
>          element of the authentication handler.</p>
>        <p>This <em>redirect-to</em> document is an unprotected pipeline in
>          sitemap. For tracking which document was originally requested by
>the user,
>          the <em>redirect-to</em> pipeline gets the request parameter
>          with that value. In addition all parameters specified inside the
>          tag of the handler configuration are passed to the pipeline as
>        <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.</p>
>     </s2>
>     </s1>
>     <s1 title="Authenticating a User">
>        <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 is constructed, there is somewhere
>where the user has 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 as a <em>login pipeline</em>.</p>
>     <s2 title="The Login Process">
>        <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>
>        <source>&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"
>    &lt;map:parameter name="parameter_password"
>    &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;
>        <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>
>        <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
>          <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
>        <p>If the user is not already authenticated with this handler, the
>framework calls
>          the <em>authentication resource</em> and passes the parameters to
>it. If this
>          authentication is successful, the action returns a map and the
>          commands inside the <em>map:act</em> are executed. If not already
>done, a session is created on
>          the server as well.</p>
>        <p>If the authentication fails, the action does not deliver a map
>        therefore the commands inside the <em>map:act</em> are skipped. The
>          information delivered by the <em>authentication resource</em> is
>stored in the
>          <em>temporary</em> context. So you can get the information using
>either the
>          <em>session transformer</em> or the <em>session-context input
>        <note>As you can see from the example above, you are not limited in
>          the information the user has to provide. This can be as many
>fields as you need.</note>
>     </s2>
>     <s2 title="The authentication resource">
>        <p>The last chapter described the authentication process but left
>          details about the authentication itself. This chapter closes this
>        <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>
>        <s3 title="Using a URI as the authentication resource">
>        <p>Using this flexible approach nearly any kind of authentication
>          possible (e.g. database, LDAP). The <em>authentication
>resource</em> is a
>          mandatory configuration of the authentication handler:</p>
>        <source>&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;
>        <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 XML conforming to the
>following scheme:</p>
>        <source>&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;
>        <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 <em>ID</em> tag is
>          an unique identification for the user inside the web application
>          more precisly inside this handler. The <em>role</em> is optional
>and can
>                           be used for categorizing users and displaying
>different functionality inside the Cocoon portal
>          engine.</p>
>        <note>The <em>role</em> element is optional; you can use your own
>        categorization and exchange it with a <em>roles</em> element or a
>        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
>        <p>Using the <em>data</em> node, the <em>authentication
>resource</em> can pass any
>          information of the user to the session. You can retrieve the
>          information as long as the session is valid.</p>
>        <p>If the authentication is not successful, the resource must
>          an XML with the root node <em>authentication</em>, 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
>          chapter).</p>
>        <note>It is advisable to make an internal pipeline for the
><em>authentication resource</em>.
>           An internal pipeline is not directly accessible by a
>        </s3>
>        <s3 title="Using a Java class as the authentication resource">
>        <p>Using a class is an alternative for using a pipeline.
>           You can define this class in the handler configuration as an
>           <em>authenticator</em> of the <em>authentication</em> element,
>        <source>&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;
>           <p>This class must conform to the <em>Authenticator</em>
>interface. This
>            interface provides a method that tries to authenticate a User
>            delivers XML that is stored in the session on success. So, the
>            is similar to the pipeline.</p>
>        </s3>
>     </s2>
>     <s2 title="Logging out">
>        <p>The logout process is triggered by the "auth-logout"
>          action:</p>
>        <source>&lt;map:act type="auth-logout"&gt;
>  &lt;map:parameter name="handler" value="unique"/&gt;
>        <p>This action logs the user out of the given handler and removes
>          the information about this handler that is stored in the
>     </s2>
>  </s1>
>  <s1 title="User Management">
>     <p>In addition to the authentication, the framework manages all kinds
>        information belonging to the user. For this reason the framework
>        creates an own session context called <em>authentication</em>. All
>        is stored in this context in an XML structure.</p>
>     <p>The authentication information (the "authentication" scheme
>        from the authentication resource) is stored in this context, so you
>        retrieve and change the information using the session transformer
>and the
>        usual getxml, setxml etc. commands, so we suggest you to read the
>        context document.</p>
>     <note>The <em>authentication</em> context is only available to the
>       <em>session transformer</em> if the pipeline in which the
>transformer is
>       running, is associated with 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.</note>
>     <s2 title="Getting information from the context">
>        <p>Each element from the context is gettable using an XML
>          tag:</p>
>        <source>&lt;session:getxml context="authentication"
>path="/authentication/ID"/&gt; &lt;!-- Get the ID --&gt;
>&lt;session:getxml context="authentication"
>        <p>The path expression is an absolute XPath-like expression where
>          concrete nodes and attributes are allowed. The session
>transformer replaces
>          the tag with the value of the first node found in the context,
>this can either
>          be text or XML.</p>
>     </s2>
>     <s2 title="Setting information in the context">
>        <p>Using another tag, information can be stored into the
>        <source>&lt;session:setxml context="authentication"
>    Mr. Sunshine
>        <p>Again the path is an absolute XPath-like expression where only
>          concrete nodes and attributes are allowed. If the requested node
>          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>
>     </s2>
>  </s1>
>  <s1 title="Application Management">
>     <p>The application management ia very useful feature for building and
>maintaining web applications.
>                         A developer uses it to configure different
>        applications and to manage the user data for these
>     <s2 title="Configuring an Application">
>        <p>A "authentication" application is related to one authentication
>handler, so an
>          application is part of the authentication handler
>        <source>&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
>                 &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;
>        <p>A configuration for an application consists of a unique name
>          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 the load
>resource (if present) for each application
>          of the handler. The content or result of the
>          load resource is stored in 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.
>                           Each application can specify if the data is
>loaded upon
>          successful authentication or the first time it is needed:</p>
>        <source>....&lt;application name="unique"
>        <p>The load resource gets several parameters: all the values of the
>          subnodes of the "authentication" node from the authentication
>context (e.g. ID, role
>          etc.) and the parameter "application" containing 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 of the parameters
>          inside the load / save tag of the handler configuration.</p>
>     </s2>
>     <s2 title="Configuring the resources">
>        <p>For managing the application the framework needs to know to
>          application a resource belongs. So in addition to the handler
>parameter the
>          auth-protect action gets the application name as a second
>        <source>&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
>    &lt;map:generate src="source/resource.xml"/&gt;
>            ...
>  &lt;/map:action&gt;
>        <p>With this mechanism each application resource can easily access
>          (and only its own) information. If a resource has no
>"application" parameter it can
>          not access information of any application.</p>
>     </s2>
>     <s2 title="Getting, setting and saving application information">
>        <p>A resource accesses its application data similar to the way is
>accesses the authentication data:</p>
>        <source>&lt;session:getxml context="authentication"
>&lt;session:setxml context="authentication"
>        <p>The path must follow the same restrictions and rules as always
>          it has to start with "/application/". </p>
>     </s2>
>  </s1>
>  <s1 title="Module Management">
>     <p>In addition to the application management feature, the framework
>offers a facility
>        called module management. It enhances the application management by
>adding the
>        possibility of configuring components for the application. For
>example, the Cocoon
>        portal engine needs information about the source of the portal
>        for the user, about where the layout is stored, etc. Each portal
>        needs this information. Assuming that a portal is an application
>        application needs this information. As only the portal engine
>itself knows what
>        information it needs, the module management is a standarized way
>        configuring such components.</p>
>     <p>The module configuration is part of the application
>        configuration:</p>
>     <source>&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
>        &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;
>     <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>
>  </s1>
>  <s1 title="User Administration">
>     <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>
>     <source>&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
>      &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
>      &lt;!-- Optional resource for deleting a role --&gt;
>      &lt;delete-role
>      &lt;!-- Optional resource for deleting a user--&gt;
>      &lt;delete-user
>    &lt;/handler&gt;
>  &lt;/handlers&gt;
>     <p>The entries are described in the following subchapters. All tags
>        have additional parameter definitions which are passed to the given
>        e.g:</p>
>     <source>&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;
>     <s2 title="Getting Roles">
>        <p>The <em>load-roles</em> resource is invoked from the framework
>          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>
>        <source>&lt;roles&gt;
>  &lt;role&gt;admin&lt;/role&gt;
>  &lt;role&gt;guest&lt;/role&gt;
>  &lt;role&gt;user&lt;/role&gt;
>     </s2>
>     <s2 title="Getting Users">
>        <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
>          </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>
>        <source>&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;
>    ...
>     </s2>
>     <s2 title="Creating a new role">
>        <p>The <em>new-role</em> resource creates a new role in the system.
>          gets the parameters "type" with the value "role" and "role" with
>the new
>          rolename.</p>
>     </s2>
>     <s2 title="Creating a new user">
>        <p>The <em>new-user</em> resource creates a new user with a role.
>          gets the parameters <em>"type"</em> with the value
>          <em>"role"</em> with the rolename and <em>"ID"</em> with the new
>ID for this
>          user.</p>
>     </s2>
>     <s2 title="Changing information of a user">
>        <p>The <em>change-user</em> resources changes information of a
>          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
>          information of this user is sent as parameters.</p>
>     </s2>
>     <s2 title="Delete a user">
>        <p>The <em>delete-user</em> resource will delete a user. It gets
>          parameters "type" with the value "user", "role" with the rolename
>and "ID" with
>          the ID of the user.</p>
>     </s2>
>     <s2 title="Delete a role">
>        <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>
>     </s2>
>  </s1>
>  <s1 title="Configuration Summary">
>     <p>Here is a brief summary of the authentication handler
>configuration: </p>
>     <source>&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;
>  </s1>
>  <s1 title="Pipeline Patterns">
>     <p>As explained in the previous chapters, the framework uses the
>        action for authentication and protecting documents. This chapter
>shows some
>        commonly used pipeline patterns.</p>
>     <s2 title="Single protected document">
>        <p>For protecting a document with an authentication handler only
>the <em>auth-protect</em>
>          action with the parameter configuration for the handler is
>        <p>Pattern:</p>
>        <ol>
>          <li>Pipeline matching
>          </li>
>          <li>Using the <em>auth-protect</em> action for protecting
>          </li>
>        </ol>
>        <p>Example:</p>
>        <source>&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;
>        <p>It is very important that the <em>auth-protect</em> action wraps
>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>
>     </s2>
>     <s2 title="Multiple protected documents">
>        <p>Often you want to protect a bunch of documents in the same way.
>          solution is to use the single protected document pattern for each
>          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>
>        <source>&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;
>        <p>Very important - as explained with the single document pattern -
>          the leading match before the action is performed. The subsequent
>matches are required
>          to check which pipeline to use.</p>
>     </s2>
>     <s2 title="Controlling the Application Flow">
>        <p>If you want to create documents which behave different depending
>if you
>          are logged in or not, the <em>auth-loggedIn</em> action is the
>component to use to
>          control your application flow. This action checks if the user is
>          for a given handler and calls all sitemap components inside the
>          tag.</p>
>        <source>&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;
>        <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>
>        <source>&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;
>        <p>But the <em>auth-loggedIn</em> action does not give the included
>          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>
>        <source>&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
>      &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;
>     </s2>
>     <s2 title="Session Handling">
>      <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 <link href="session.html">chapter about sessions</link>.</p>
>     </s2>
>  </s1>

View raw message