cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Carsten Ziegeler <>
Subject Re: [Fwd: Re: Cocoon - modified authentication.xml]
Date Fri, 12 Aug 2005 09:08:23 GMT
Hi Ron,

thanks for your updates. I just applied them to subversion.

If you have any questions or want to provide more updates, additional
docs etc., please direct them to the cocoon developer list


Ron Wheeler schrieb:
> 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 
> authentication.xml
> 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.
> Ron
> -------- Original Message --------
> Subject: 	Re: Cocoon - modified authentication.xml
> Date: 	Fri, 05 Aug 2005 09:58:14 -0400
> From: 	Ron Wheeler <>
> Reply-To:
> Organization: 	Artifact
> To:
> References: 
> <>
> 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
>>S&N AG
>>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>

Carsten Ziegeler - Open Source Group, S&N AG

View raw message