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 (dev@cocoon.apache.org) Thanks Carsten 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 <[EMAIL PROTECTED]> > Reply-To: [EMAIL PROTECTED] > Organization: Artifact > To: [EMAIL PROTECTED] > References: > <[EMAIL PROTECTED]> > > > > 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 > > > [EMAIL PROTECTED] 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 >>(dev@cocoon.apache.org). 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 >>parameter >>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 >>transformer >>which means the transformer does not pass this tag to the next component in >>the pipeline. >> >> >> >> >>>398 "sides" - do you mean "sites" >>> >>> >> >>Yes. >> >> >> >> >>>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 >>> >>> >> >>user. >> >> >> >>> It gets the parameters "type" with the value "user", "role" >>>with the rolename >>> and "ID" with the ID of the user. In addition all application >>>specific >>> information of this user is 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, >>the >>authentication framework calls this "change-user" resource (or pipeline) >>and >>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 >>database >>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 >>> >>> >> >>the >> >> >> >>> 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 >>then >>call this resource, provide the required parameters and it will delete the >>user. >> >>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 >>Carsten >>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 >>eMail [EMAIL PROTECTED] >>web http://www.s-und-n.de >> >> >> >> >> >> Ron Wheeler >> >> <[EMAIL PROTECTED] An: [EMAIL PROTECTED] >> >> ftware.com> 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 >>problems. >> >>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. >> >>Ron >> >> >>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 >>user. >> It gets the parameters "type" with the value "user", "role" >>with the rolename >> and "ID" with the ID of the user. In addition all application >>specific >> information of this user is 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 >>the >> 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 >> >> http://www.apache.org/licenses/LICENSE-2.0 >> >> Unless required >>by applicable law or agreed to in writing, software >> distributed under the >>License is distributed on an "AS IS" BASIS, >> WITHOUT WARRANTIES OR >>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" >>"document-v10.dtd"> >><document> >> <header> >> <title>Authentication Framework</title> >> <authors> >> <person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/> >> </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 >><em>auth-protect</em> >> action, the <em>auth-login</em> action, the <em>auth-logout</em> >>action >> and the <em>auth-loggedIn</em> action. The >><em>authentication-manager</em> gets >> the configuration for the authentication framework and the actions >>controle the pipelines. >> The <em>auth-login</em> and the <em>auth-logout</em> action control >>the >> authentication whereas the <em>auth-loggedIn</em> action controls >>the application >> flow.</p> >> <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 >>document. >> </li> >> <li>If the document is protected, the framework checks, if the user >>is >> authenticated to view it. >> </li> >> <li>If the user is authenticated, the response is the original >> document. If not, the framework redirects to a special >>redirect-to document. This >> redirect-to document is freely configurable and 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 >>process. >> </li> >> <li>In case of a successful authentication the framework can >>redirect to >> the original document (or to any configured start document). >> </li> >> <li>If the authentication fails another document is invoked by >> the framework displaying information to the user. >> </li> >> </ol> >> <p>This process is only one example for a use-case of the framework. >>It >> can be configured for any authentication scheme. All resources are >>freely >> configurable.</p> >> <s2 title="The Authentication handler"> >> <p>The basic object for authentication is the authentication >>handler. >> It controlles the access to the documents. Each >>document in the >> sitemap can be related to exactly one authentication handler. All >>documents belonging >> to the same handler are protected in the same way. If a user has >>access to the >> handler, the user has the same access rights for all documents >>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> >><source> >><map:sitemap> >> ...component definitions... >> >><map:pipelines> >> <map:component-configurations> >> <authentication-manager> >> <handlers> >> <handler name="portalhandler"> >> <redirect-to uri="cocoon:/sunspotdemoportal"/> >> <authentication uri="cocoon:raw:/sunrise-authuser"/> >> </handler> >> </handlers> >> </authentication-manager> >> </map:component-configurations> >><map:pipeline> >> ... document pipelines following here: >></source> >> <p>Using a unique name for each handler (only alphabetical >>characters >> and digits are allowed for the handler name), the framework >>manages different >> handlers. So various parts of the sitemap can be protected in >>different ways. >> </p> >> <p>A handler is inherited to a sub sitemap. Each sub sitemap can >>define >> its own handlers. These handlers are only available to the sub >>sitemap >> (and of course to its sub sitemaps). However, it is not possible >>to >> redefine (overwrite) a previously defined handler in a sub >>sitemap.</p> >> </s2> >> <s2 title="Protecting Documents"> >> <p>A document is protected by associating it with a defined >>handler. >> This is done by using the <em>auth-protect</em> action and the >>handler parameter:</p> >><source><map:match pattern="protectedresource"> >> <map:act type="auth-protect"> >> <map:parameter name="handler" value="portalhandler"/> >> <map:generate src="source/resource.xml"/> >> <map:serialize type="xml"/> >> </map:act> >></map:match></source> >> <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 >>the >> sitemap. For tracking which document was originally requested by >>the user, >> the <em>redirect-to</em> pipeline gets the request parameter >><em>resource</em> >> with that value. In addition all parameters specified inside the >><em>redirect-to</em> >> tag of the handler configuration are passed to the pipeline as >>well.</p> >> <p>For example, the <em>redirect-to</em> document can contain a >>form for the user >> authentication. This form should invoke the real authentication >>process that is >> described below.</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><map:match pattern="login"> >> <map:act type="auth-login"> >> <map:parameter name="handler" value="portalhandler"/> >> <map:parameter name="parameter_userid" >>value="{request-param:name}"/> >> <map:parameter name="parameter_password" >>value="{request-param:password}"/> >> <map:redirect-to uri="authentication-successful"/> >> </map:act> >> <!-- authentication failed: --> >> <map:generate src="auth_failed.xml"/> >> <map:transform src="tohtml.xsl"/> >> <map:serialize/> >></map:match></source> >> <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 >>use >> <em>cocoon:</em> then the parameters of the form are by default >>passed on >> to the <em>authentication resource</em> and we could omit the >>parameter definition >> from above. But we feel that it is safer to explicitly define >>them.</note> >> <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 >>sitemap >> 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 >>and >> therefore the commands inside the <em>map:act</em> are skipped. The >>error >> 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 >>module</em>.</p> >> <note>As you can see from the example above, you are not limited in >>defining >> the information the user has to provide. This can be as many >>fields as you need.</note> >> </s2> >> <s2 title="The authentication resource"> >> <p>The last chapter described the authentication process but left >>out >> details about the authentication itself. This chapter closes this >>gap.</p> >> <p>The authentication can be done by different components:</p> >> <ul> >> <li>A sitemap resource (pipeline). >> </li> >> <li>A distant resource, e.g. requested via HTTP. >> </li> >> <li>A java class. >> </li> >> </ul> >> <p>The first two are actually similar as in both cases a URI is >>called. So we >> will talk about them in the next chapter. Authentication using a >>java class >> is the topic of the following chapter.</p> >> <s3 title="Using a URI as the authentication resource"> >> <p>Using this flexible approach nearly any kind of authentication >>is >> possible (e.g. database, LDAP). The <em>authentication >>resource</em> is a >> mandatory configuration of the authentication handler:</p> >> <source><autentication-manager> >> <handlers> >> <!-- Now follows the handlers configuration --> >> <handler name="portalhandler"> >> <!-- The login resource --> >> <redirect-to uri="cocoon:/sunspotdemoportal"/> >> <authentication uri="cocoon:raw:/sunrise-authuser"/> >> </handler> >> </handlers> >></autentication-manager></source> >> <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><authentication> >> <ID>Unique ID of the user in the system</ID> >> <role>rolename</role> <!-- optional --> >> <data> >> Any additional optional information can be supplied here. >> This will be stored in the session for later retrieval >> </data> >></authentication></source> >> <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 >>or >> 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 >><em>group</em> >> element or leave it out, if you don't need it. In addition you can >>add any >> other element there as well and access the information later >>on.</note> >> <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 >>create >> 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 >>previous >> 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 >>user.</note> >> </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 >>attribute >> <em>authenticator</em> of the <em>authentication</em> element, >>e.g.:</p> >> <source><autentication-manager> >> <handlers> >> <!-- Now follows the handlers configuration --> >> <handler name="portalhandler"> >> <!-- The login resource --> >> <redirect-to uri="cocoon:/sunspotdemoportal"/> >> <authentication authenticator="mypkg.MyAuthenticator"/> >> </handler> >> </handlers> >></autentication-manager></source> >> <p>This class must conform to the <em>Authenticator</em> >>interface. This >> interface provides a method that tries to authenticate a User >>and >> delivers XML that is stored in the session on success. So, the >>behaviour >> is similar to the pipeline.</p> >> </s3> >> </s2> >> <s2 title="Logging out"> >> <p>The logout process is triggered by the "auth-logout" >> action:</p> >> <source><map:act type="auth-logout"> >> <map:parameter name="handler" value="unique"/> >></map:act></source> >> <p>This action logs the user out of the given handler and removes >>all >> the information about this handler that is stored in the >>session.</p> >> </s2> >> </s1> >> <s1 title="User Management"> >> <p>In addition to the authentication, the framework manages all kinds >>of >> information belonging to the user. For this reason the framework >> creates an own session context called <em>authentication</em>. All >>information >> is stored in this context in an XML structure.</p> >> <p>The authentication information (the "authentication" scheme >>retrieved >> from the authentication resource) is stored in this context, so you >>can >> retrieve and change the information using the session transformer >>and the >> usual getxml, setxml etc. commands, so we suggest you to read the >>session >> context document.</p> >> <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><session:getxml context="authentication" >>path="/authentication/ID"/> <!-- Get the ID --> >><session:getxml context="authentication" >>path="/authentication/data/username"/></source> >> <p>The path expression is an absolute XPath-like expression where >>only >> 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 >>context:</p> >> <source><session:setxml context="authentication" >>path="/authentication/data/usersername"> >> Mr. Sunshine >></session:setxml></source> >> <p>Again the path is an absolute XPath-like expression where only >> concrete nodes and attributes are allowed. If the requested node >>exists, >> the framework changes the value of that node. If the node does >>not exists, the framework >> adds it to the context with the given value.</p> >> <p>The tag is removed from the resource.</p> >> </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 >>applications.</p> >> <s2 title="Configuring an Application"> >> <p>A "authentication" application is related to one authentication >>handler, so an >> application is part of the authentication handler >>configuration:</p> >> <source><autentication-manager> >> <handlers> >> <handler name="unique"> >> ....redirect-to/authentication configuration >> <applications> <!-- the applications for this handler >>--> >> <application name="unique"> >> <load uri="loadapp"/> <!-- optional --> >> <save uri="saveapp"/> <!-- optional --> >> </application> >> </applications> >> </handler> >> </handlers> >></autentication-manager></source> >> <p>A configuration for an application consists of a unique name >>(only >> alphabetical characters and digits are allowed for the >>application name) and >> optional load and save resources. The application configuration >>can contain >> application specific configuration values for the various parts >>of the >> application, e.g. information for a portal.</p> >> <p>On a successful authentication, the framework invokes 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>....<application name="unique" >>loadondemand="true"/>...</source> >> <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 >>specified >> 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 >>which >> application a resource belongs. So in addition to the handler >>parameter the >> auth-protect action gets the application name as a second >>parameter:</p> >> <source><map:match pattern="protectedresource"> >> <map:action type="auth-protect"> >> <map:parameter name="handler" value="unique handler name"/> >> <map:parameter name="application" value="unique application >>name"/> >> >> <map:generate src="source/resource.xml"/> >> ... >> </map:action> >></map:match> >></source> >> <p>With this mechanism each application resource can easily access >>its >> (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><session:getxml context="authentication" >>path="/application/username"/> >><session:setxml context="authentication" >>path="/application/shoppingcart"><item1/><item2/></session:setxml></source> >> >> <p>The path must follow the same restrictions and rules as always >>and >> 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 >>profile >> for the user, about where the layout is stored, etc. Each portal >> needs this information. Assuming that a portal is an application >>each >> application needs this information. As only the portal engine >>itself knows what >> information it needs, the module management is a standarized way >>for >> configuring such components.</p> >> <p>The module configuration is part of the application >> configuration:</p> >> <source><autentication-manager> >> <handlers> >> <handler name="unique"> >> ....redirect-to/authentication configuration >> <applications> <!-- the applications for this handler >>--> >> <application name="unique"> >> ... >> <configuration name="portal"> >> ...portal configuration >> </configuration> >> </application> >> </applications> >> </handler> >> </handlers> >></autentication-manager></source> >> <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><autentication-manager> >> <handlers> >> <handler name="unique"> >> ...redirect-to/authentication configuration... >> >> <!-- Optional resource for loading user information --> >> <load-users >>uri="cocoon:raw://financeresource-sunrise-loaduser"/> >> >> <!-- Optional resource for loading roles information--> >> <load-roles uri="cocoon:raw://financeresource-sunrise-roles"/> >> >> <!-- Optional resource for creating a new user --> >> <new-user uri="cocoon:raw://financeresource-sunrise-newuser"/> >> >> <!-- Optional resource for creating a new role --> >> <new-role uri="cocoon:raw://financeresource-sunrise-newrole"/> >> >> <!-- Optional resource for changing user information --> >> <change-user >>uri="cocoon:raw://financeresource-sunrise-newuser"/> >> >> <!-- Optional resource for deleting a role --> >> <delete-role >>uri="cocoon:raw://financeresource-sunrise-delrole"/> >> >> <!-- Optional resource for deleting a user--> >> <delete-user >>uri="cocoon:raw://financeresource-sunrise-deluser"/> >> </handler> >> </handlers> >></autentication-manager></source> >> <p>The entries are described in the following subchapters. All tags >>can >> have additional parameter definitions which are passed to the given >>resource, >> e.g:</p> >> <source><!-- Optional resource for deleting a user--> >><delete-user uri="cocoon:raw://financeresource-sunrise-deluser"> >> <connection>database</connection> >> <url>db:usertable</url> >></delete-user></source> >> <s2 title="Getting Roles"> >> <p>The <em>load-roles</em> resource is invoked from the framework >>whenever >> it needs information about the available roles. This resource >>gets the >> parameter "type" with the value "roles" and should deliver an XML >>schema with >> the root node "roles" and for each role a subelement "role" with >>a text child >> of the rolename:</p> >> <source><roles> >> <role>admin</role> >> <role>guest</role> >> <role>user</role> >></roles></source> >> </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 >>rolename. >> </li> >> <li>Load information of one user. The resource gets the >> parameters "type" with the value "user", "role" with the >>rolename and "ID" with >> the authentication ID of the user. >> </li> >> </ul> >> <p>The XML format of the resource should look like the >> following:</p> >> <source><users> >> <user> >> <ID>authentication ID</ID> >> <role>rolename</role> >> <data> >> ... application specific data ... >> </data> >> </user> >> <user> >> ... >> </user> >> ... >></users></source> >> </s2> >> <s2 title="Creating a new role"> >> <p>The <em>new-role</em> resource creates a new role in the system. >>It >> gets the parameters "type" with the value "role" and "role" with >>the new >> rolename.</p> >> </s2> >> <s2 title="Creating a new user"> >> <p>The <em>new-user</em> resource creates a new user with a role. >>It >> gets the parameters <em>"type"</em> with the value >><em>"user"</em>, >> <em>"role"</em> with the rolename and <em>"ID"</em> with the new >>ID for this >> user.</p> >> </s2> >> <s2 title="Changing information of a user"> >> <p>The <em>change-user</em> resources changes information of a >>user. >> It gets the parameters "type" with the value "user", "role" with >>the rolename >> and "ID" with the ID of the user. In addition all application >>specific >> information of this user is sent as parameters.</p> >> </s2> >> <s2 title="Delete a user"> >> <p>The <em>delete-user</em> resource will delete a user. It gets >>the >> parameters "type" with the value "user", "role" with the rolename >>and "ID" with >> the ID of the user.</p> >> </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><autentication-manager> >> <handlers> >> <handler name="unique"> >> <!-- The redirect-to resource --> >> <redirect-to uri="cocoon:raw://loginpage"/> >> <!-- Authentication resource --> >> <authentication uri="cocoon:raw://authenticationresource"/> >> >> <load uri="cocoon:raw://authenticationsaveresource"> >> <!-- optional parameters --> >> </load> >> <!-- optional save resource --> >> <save uri="cocoon:raw://authenticationsaveresource"> >> <!-- optional parameters --> >> </save> >> >> <applications> >> <!-- the applications for this handler --> >> <application name="unique"> >> >> <!-- Loading/Saving --> >> <load uri="cocoon:raw://loadapp"> >> <!-- optional --> >> <!-- optional parameters --> >> </load> >> <save uri="cocoon:raw://saveapp"> >> <!-- optional --> >> <!-- optional parameters --> >> </save> >> <!-- module configurations: --> >> >> <configuration name="portal"> >> ...portal configuration >> </configuration> >> </application> >> </applications> >> >> </handler> >> </handlers> >></autentication-manager></source> >> </s1> >> <s1 title="Pipeline Patterns"> >> <p>As explained in the previous chapters, the framework uses the >><em>auth-protect</em> >> action for authentication and protecting documents. This chapter >>shows some >> 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 >>required.</p> >> <p>Pattern:</p> >> <ol> >> <li>Pipeline matching >> </li> >> <li>Using the <em>auth-protect</em> action for protecting >> </li> >> </ol> >> <p>Example:</p> >> <source><map:match pattern="protected"> >> <map:act type="auth-protect"> <!-- protect the resource --> >> <map:parameter name="handler" value="myhandler"/> >> >> <map:generate src="resource.xml"/> >> <map:transform src="toHTML"/> >> <map:serialize/> >> </map:act> >></map:match></source> >> <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. >>One >> solution is to use the single protected document pattern for each >>document. >> With the multiple protected document pattern you only have to use >>the action >> once for all documents and not within each document pipeline.</p> >> <p>The prerequisite for this is a common matching pattern for the >> documents:</p> >> <ol> >> <li>Pipeline pattern matching >> </li> >> <li>Using the <em>auth-protect</em> action for protection >> </li> >> <li>Pipeline matching >> </li> >> </ol> >> <p>Example:</p> >> <source><map:match pattern="protected-*"> >> <map:act type="auth-protect"> <!-- protect the resource --> >> <map:parameter name="handler" value="myhandler"/> >> >> <map:match pattern="protected-first"> >> <map:generate src="resource1.xml"/> >> <map:transform src="toHTML"/> >> <map:serialize/> >> </map:match> >> .... >> <map:match pattern="protected-second"> >> <map:generate src="resource2.xml"/> >> <map:transform src="toHTML"/> >> <map:serialize/> >> </map:match> >> >> </map:act> >></map:match></source> >> <p>Very important - as explained with the single document pattern - >>is >> 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 >>authenticated >> for a given handler and calls all sitemap components inside the >><em>act</em> >> tag.</p> >> <source><map:match pattern="startpage"> >> >> <map:act type="auth-loggedIn"> <!-- check authentication --> >> <map:parameter name="handler" value="myhandler"/> >> >> <map:redirect-to uri="loggedInStartPage"/> >> </map:act> >> >> <map:generate src="startpage.xml"/> >> <map:transform src="toHTML"/> >> <map:serialize/> >></map:match></source> >> <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><map:match pattern"protected"> >> <map:act type="auth-protect"> <!-- protect the resource --> >> <map:parameter name="handler" value="myhandler"/> >> >> <!-- Append the ID of the user to the file name --> >> <map:generate src="resource_{ID}.xml"/> >> <map:transform src="toHTML"/> >> <map:serialize/> >> >> </map:act> >></map:match></source> >> <p>But the <em>auth-loggedIn</em> action does not give the included >>pipeline >> access to the authentication context belonging to the handler. If >>you want this, you >> have to nest the <em>auth-protect</em> action inside!</p> >> <source><map:match pattern"start"> >> >> <map:act type="auth-loggedIn"> <!-- check authentication --> >> <map:parameter name="handler" value="myhandler"/> >> >> <map:act type="auth-protect"> <!-- give access to the context >>--> >> <map:parameter name="handler" value="myhandler"/> >> >> <map:generate src="getinfofromcontext.xml"/> >> <map:transform type="session"/> >> <map:transform src="toHTML"/> >> <map:serialize/> >> </map:act> >> </map:act> >> >></map:match></source> >> </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> >></body> >></document> >> >> >> >> >> >> >> >> > > -- Carsten Ziegeler - Open Source Group, S&N AG http://www.s-und-n.de http://www.osoco.org/weblogs/rael/
